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为 什么 要 写 这 本 书 


目 第 1 版 发 行 以 来 ， 笔 者 很 欣慰 得 到 了 广大 读者 的 认可 。 本 书 一 直 
致力 于 说 明 开 发 Nginx 模 块 的 必 备 知识 ， 然 而 由 于 Nginx 功 能 繁多 旦 性 
能 强大 ， 以 致 必须 要 了 解 的 基本 近 能 也 很 庞杂 ， 而 第 1 版 成 书 缴 忙 ， 缺 
失 了 几 个 进 阶 的 技巧 描述 (例如 如 何 使 用 变量 、slab 共 享 内 存 等 )， 
因此 决定 在 第 1 版 的 基础 上 进一步 完善 。 


事实 上 ， 我 们 总 能 在 nginx.conf 配 置 文 件 中 看 到 各 种 沉着 $ 符 号 的 
， 只 要 修改 市 厦 变 量 的 这 一 行 行 配置 ， 束 可 以 不 用 编译 、 部 署 而 
E， 这 些 文 持 变量 的 Nginx 模 块 提 供 了 极为 灵活 的 
功能 ， 第 2 版 通过 新 增 的 第 15 章 详细 介绍 了 如 何在 模块 中 支持 HITP 变 
量 ， 包 括 如 何在 代码 中 使 用 其 他 Nginx 模 块 提供 的 变量 ， 以 及 如 何 定义 
新 的 变量 供 nginx.conf 和 其 他 第 三 方 模块 使 用 等 。 第 16 章 介绍 了 slab 共 
译 内 存 ， 这 古 一 套 适 用 于 小 块 内 存 快 速 分 配 释 放 的 内 存 管理 方式 ， 它 
非常 高 效 ， 分 配 与 释放 速度 都 是 以 纳 秒 计算 的 ， 常 用 于 多 个 worker 进 
程 之 间 的 通信 ， 这 比 第 14 章 介绍 的 原始 的 共 译 内 存 通信 方式 要 先进 很 
多 。 第 16 章 不 仅 详 细 介绍 了 它 的 实现 方式 ， 也 探讨 了 它 的 优 缺 点 ， 比 
如 ， 如 末 模 块 间 要 共 至 的 单个 对 象 常 常 要 消耗 数 KB 的 空间 ， 这 时 就 需 


要 修改 它 的 实现 〈 例 如 增 大 定义 的 slab 页 大 小 ) ， 以 避免 内 存 的 浪费 


4 。 
于 


Nginx 内 存 池 在 第 1 版 中 只 是 简单 党 过 ， 第 2 版 中 新 增 了 8.7 市 介绍 
了 内 存 池 的 实现 细 市 ， 以 帮助 读者 用 好 最 基础 的 内 存 池 功能 。 


此 外 ， 很 多 读者 反馈 需要 结合 TCP 来 谈 谈 Nginx， 因 此 在 9.10 节 中 
笔者 试图 在 不 陷入 Linux 内 核 细 节 的 情况 下 ， 简 要 介绍 了 TCP 以 清晰 了 
解 Nginx 的 事件 框架 ， 了 解 Nginx 的 高 并 发 能 力 。 


这 一 版 新 增 的 第 15 半 的 样 例 代码 可 以 从 http://nginx.taohui.org.cn 站 
点 上 下 载 。 


因 笔 者 工作 繁忙 ， 以 致 第 2 版 拖 稿 严重 ， 读 者 的 邮件 也 无 法 及 时 回 
复 ， 非 常 抱歉 。 从 这 版 开始 会 把 曾经 的 回复 整理 后 放 在 网 站 上 ， 想 必 
这 比 回复 邮件 要 更 有 效率 些 。 
读者 对 象 

本 书 适 合 以 下 读者 阅读 。 


-对 Nginx 及 如 何 将 它 搭 建成 一 个 高 性 能 的 Web 服 务 右 感 兴趣 的 
者 。 


' 硕 望 通过 开发 特定 的 HTTP 模 块 实现 高 性 能 Web 服 务 硕 的 读者 。 
:布衣 了 解 Nginx 的 架构 设计 ， 学 习 其 怎样 充分 使 用 服务 右上 的 硬 
件 资 源 的 读者 。 


:了解 如 何 快速 定位 、 修 复 Nginx 中 深层 次 Bug 的 读者 。 


-希望 利用 Nginx 提 供 的 框 漆 ， 设 计 出 任何 基于 TCP 的 、 无 阻 压 
的 、 易 于 扩展 的 服务 器 的 读者 。 


= Ny 
背景 知识 


如 果 仅 希望 了 解 怎样 使 用 已 有 的 Nginx 功 能 搭建 服务 器 ， 那 么 阅读 
本 书 不 需要 什么 先决 条 件 。 但 如 果 硕 望 通过 阅读 本 书 的 第 二 、 第 三 两 
部 分 ， 来 学 习 Nginx 的 模块 开发 和 架构 设计 技巧 时 ， 则 必须 了 解 C 语 言 
的 基本 语法 。 在 阅读 本 书 第 三 部 分 时 ， 需 要 读者 对 TCP 有 一 个 基本 的 
了 解 ， 同 时 对 Linux 操 作 系统 也 应 该 有 人 简单 的 了 解 。 


如 何 阅 读本 书 


我 很 希望 将 本 书写 成 一 本 “step by step” 式 (循序 渐进 式 ) 的 书 
籍 ， 因 为 这 样 最 能 节省 读者 的 时 间 ， 然 而 ， 由 于 3 个 主要 写作 目的 想 解 
决 的 问题 都 不 是 那么 简单 ， 所 以 这 本 书 只 能 做 一 个 折 中 的 处 理 。 


在 第 一 部 分 的 前 两 章 中 ， 将 只 探讨 如 何 使 用 Nginx 这 一 个 问题 。 阅 
读 这 一 部 分 的 读者 不 需要 了 解 C 语 言 ， 融 可 以 学 习 如 何 部 署 Nginx， 学 
习 如 何 向 其 中 添加 各 种 官方 、 第 三 方 的 功能 模块 ， 如 何 通 过 修改 配置 
文件 来 更 改 Nginx 及 各 模块 的 功能 ， 如 何 修改 Linux 操 作 系统 上 的 参数 
来 优化 服务 硕 性 能 ， 最 终 同 用 户 提供 企业 级 的 web 服务 右 。 这 一 部 分 
介绍 配置 项 的 方式 ， 更 偏重 于 领 大 对 Nginx 还 比较 了 生 的 读者 熟悉 它 
通过 了 解 几 个 基本 Nginx 模 块 的 配置 修改 方式 ， 进 而 使 读者 可 以 通过 查 
询 官 网 、 第 三 方 网 站 来 了 解 如 何 使 用 所 有 Nginx 模 块 的 用 法 。 
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在 第 二 部 分 的 第 3 草 ~ 第 7 章 中 ， 部 是 以 例子 来 介绍 HTTP 模 块 的 开 
发 方式 的 ， 这 里 有 些 接近 于 “step by step” 的 学 习 方式 ， 我 在 写作 这 一 
部分 时 ， 会 通过 循序 渐进 的 方式 使 读者 能 够 快速 上 手 ， 同 时 会 穿插 着 

绍 其 常见 用 法 的 基本 原理 。 


KE 


> 


在 第 三 部 分 ， 将 开始 介绍 Nginx 的 完整 框架 ， 阅 读 到 这 里 将 会 了 解 
第 二 部 分 中 HTTP 模 块 为 何以 此 种 方式 开发 ， 同 时 将 可 以 轻易 地 开发 
Nginx 模 块 。 这 一 部 分 并 不 仅仅 满足 于 阐述 Nginx 染 构 ， 而 是 会 探讨 其 
为 何如 此 设计 ， 只 有 这 样 才 能 抛 开 HTTP 框 架 、 邮 件 代理 框架 ， 实 现 一 
种 新 的 业务 框架 、 一 种 新 的 模块 类 型 。 


对 于 Nginx 的 使 用 还 不 熟悉 的 读者 应 当 从 第 1 革 开 始 学 习 ， 前 两 章 
将 帮助 你 快速 了 解 Nginx 。 


使 用 过 Nginx， 但 对 如 何 开 发 Nginx 的 HTTP 模 块 不 太 了 解 的 读者 可 
以 直接 从 第 3 章 开始 学 习 ， 在 这 一 章 阅 读 完 后 ， 即 可 编写 一 个 功能 大 致 
完整 的 HITP 模 块 。 然 而， 编写 企业 级 的 模块 必须 阅读 完 第 4 章 才 能 做 
到 ， 这 一 章 将 会 介绍 编写 产品 线 上 服务 器 程序 时 必 备 的 3 个 手段 。 第 5 
章 举例 说 明了 两 种 编写 复杂 HTTP 模 块 的 方式 ， 在 第 三 部 分 会 对 这 两 个 
方式 有 进一步 的 说 明 。 第 6 章 介绍 一 种 特殊 的 HITP 模 块 一 一 HTTP 过 滤 
模块 的 编写 方法 。 第 7 章 探讨 基础 容器 的 用 法 ， 这 同样 是 复杂 模块 的 必 
备 工具 。 


如 有 果 读 者 对 于 普通 HTTP 模 块 的 编写 已 经 很 熟悉 ， 想 深入 地 实现 更 
为 复杂 的 HTTP 模 块 ， 或 者 想 了 解 邮件 代理 服务 器 的 设计 与 实现 ， 或 者 
希望 编写 一 种 新 的 处 理 其 他 协议 的 模块 ， 或 者 仅仅 想 了 解 Nginx 的 架构 
设计 ， 都 可 以 直接 从 第 8 章 开始 学 习 ， 这 一 章 会 从 整体 上 系统 介绍 
Nginx 的 模块 式 设计 。 第 9 章 的 事件 框架 是 Nginx 处 理 TCP 的 基础 ， 这 一 
章 无 法 跳 过 。 阅 读 第 8 章 、 第 9 章 时 可 能 会 遇 到 许多 第 7 章 介绍 过 的 容 
器 ， 这 时 可 以 回 到 第 7 章 碍 询 其 用 法 和 意义 。 第 10 章 ~ 第 12 章 在 介绍 
HTTP 框 架 ， 通 过 这 3 章 的 学 习 会 对 HTTP 模 块 的 开发 有 深入 的 了 解 ， 同 
时 可 以 学 习 HTTP 框 染 的 优秀 设计 。 第 13 章 简单 介绍 了 邮件 代理 服务 右 
的 设计 ， 它 近似 于 简化 版 的 HTTP 框 架 。 第 14 章 介绍 了 进程 间 同 步 的 工 
具 。 第 15 章 介绍 了 HTTP 变 量 ， 包 括 如 何 使 用 已 有 变量 、 支 持 用 户 在 
nginx.conf 中 修改 变量 的 值 、 支 持 其 他 模块 开发 者 使 用 自己 定义 的 变量 


等 。 第 16 章 介绍 了 slab 共 享 内 存 ， 该 内 存 极为 高 效 ， 可 用 于 多 个 worker 
进程 间 的 通信 。 


为 了 不 让 读者 陷入 代码 的 “汪洋 大 海 " 中 ， 在 本 书 中 大 量 使 用 了 
表 ， 这 样 可 以 使 读者 快速 、 大 体 地 了 解 流 程 和 原理 ， 在 这 基础 上 ， 如 
果 读 者 还 希望 了 解 代 码 是 如 何 实现 的 ， 可 以 针对 性 地 阅读 源 代码 中 的 
相应 方法 。 在 代码 的 天 键 地 方 会 通过 添加 注释 的 方式 加 以 说 明 。 和 希望 
这 种 方式 能 够 帮助 读者 减少 阅读 花费 的 时 间 ， 更 快 、 更 好 地 把 握 仁 
Nginx， 同 时 深入 到 细 廊 中。 


写作 本 书 第 1 版 时 ，Nginx 的 最 新 稳定 版 本 是 1.0.14， 所 以 当时 是 基 
于 此 版 本 来 写作 的 。 截 止 到 第 2 版 完成 时 ，Nginx 的 稳定 版 本 已 经 上 升 
到 了 1.8.0。 但 这 不 会 对 本 书 的 阅读 造成 困惑 ， 笔 者 验证 过 示例 代码 ， 
均 可 以 运行 在 最 新 版 本 的 Nginx 中 ， 这 是 因为 本 书 主要 是 在 介绍 Nginx 
的 基本 框 如 代码 ， 以 及 怎样 使 用 这 些 框架 代码 开发 新 的 Nginx 模 块 。 在 
这 些 基本 框架 代码 中 ，Nginx 一 般 不 会 做 任何 改变 ， 否 则 已 有 的 大 量 
Nginx 模 块 将 无 法 工作 ， 这 种 损失 是 不 可 承受 的 。 而 且 Nginx 框 架 为 具 
体 的 功能 模块 提供 了 足够 的 灵活 性 ， 修 改 功能 时 很 少 需要 修改 框架 代 
码 。 


Nginx 是 跨 平台 的 服务 硕 ， 然 而 这 本 书 将 只 针对 于 最 第 见 的 Linux 
操作 系统 进行 分 机 ， 这 样 做 一 方面 是 篇 幅 所 限 ， 必 一 方面 则 是 本 书 的 
写作 目的 主要 在 于 告诉 大 家 如 何 基于 Nginx 编 写 代 码 ， 而 不 是 怎样 在 一 


个 具体 的 操作 系统 上 修改 配置 使 用 Nginx。 因 此 ， 即 使 本 书 以 Linux 系 
统 为 代表 讲述 Nginx， 也 不 会 影响 使 用 其 他 操作 系统 的 读者 阅读 ， 操 作 
系统 的 差别 相对 于 本 书 内 容 的 影响 实在 是 非常 小 。 


勘误 和 文 持 


由 于 作者 的 水 平 有 限 ， 加 之 编写 的 时 间 也 很 仓促 ， 书 中 难免 会 出 
现 一 些 错误 或 者 不 准确 的 地 方 ， 奶 请 读者 批评 指正 。 为 此 ， 我 特意 创 
建 了 一 个 在 线 支持 与 应 急 方案 的 二 级 站 点 : http://nginx.weebly.com 。 
读者 可 以 将 书 中 的 错误 发 布 在 Bug 勘 误 表 页 面 中 ， 同 时 如 果 读 者 遇 到 
任何 问题 ， 也 可 以 访问 Q&A 页 面 ， 我 将 尽量 在 线 上 为 读者 提供 最 满意 
的 解答 。 书 中 的 全 部 源 文件 都 将 发 布 在 这 个 网 站 上 ， 我 也 会 将 相应 的 
功能 更 新 及 时 发 布 出 来 。 如 有 果 你 有 更 多 的 至 贵 意见 ， 也 欢迎 你 发 送 邮 
件 至 我 的 邮箱 russelltao@foxmailcom， 期 待 能 够 听 到 读者 的 真 执 反 


馈 。 


致谢 


我 目 先 要 感谢 Igor Sysoev， 他 在 Nginx 设 计 上 展现 的 功力 令 人 折 
服 ， 正 是 他 的 工作 成 果 才 有 了 本 书 诞生 的 意义 。 


lisa 是 机 械 工 业 出 版 社 华章 公司 的 优秀 编辑 ， 非 常 值得 信任 。 在 这 
半年 的 写作 过 程 中 ， 她 花费 了 很 多 时 间 、 精 力 来 阅读 我 的 书稿 ， 指 出 
了 许多 文字 上 和 格式 上 的 错误 ， 她 提出 的 建议 都 大 大 提高 了 本 书 的 可 


读 性 。 


在 这 半年 时 间 里 ,一边 工作 一 边 写作 给 我 这 来 了 很 大 的 压力 ， 所 
以 我 要 感谢 我 的 父母 在 生活 上 对 我 无 微 不 至 的 照顾 ， 使 我 可 以 全 力 投 
入 到 写作 中 。 和 繁忙 的 工作 之 余 ， 写 作 又 占用 了 休 忆 时 间 的 绝 大 部 分 ， 
感谢 我 的 太太 毛 业 勤 对 我 的 体谅 和 鼓励 ， 让 我 始终 以 高 昂 的 斗志 投入 
到 本 书 的 写作 中 。 


感谢 我 工作 中 的 同事 们 ， 正 是 在 与 他 们 一 起 战斗 在 一 线 的 日 子 
里 ， 我 才 不 断 地 对 技术 有 新 地 感 恒 ， 正 是 那些 充满 沿 情 的 岁月 ， 才 使 
得 我 越 来 越 热 爱 服务 絮 技 术 的 开发 。 


刘 以 此 书 ， 献 给 我 最 杀 爱 的 家 人 ， 以 及 众多 热爱 Nginx 的 朋友 。 
陶 瘤 


2015 年 10 月 


第 一 部 分 “Nginx 能 帮 有 我 们 做 什么 


革 ”人 研究 Nginx 前 的 准备 工作 


章 ”Nginx 的 配置 


第 1 章 ”研究 Nginx 前 的 准备 工作 


2012 年 ，Nginx 采 获 年 度 云 计 算 开 发 奖 (2012 Cloud Award for 
Developer of the Year) ， 并 成 长 为 世界 第 二 大 Web 服 务 器 。 全 世界 流 
量 最 高 的 前 1000 名 网 站 中 ， 超 过 25% 都 使 用 Nginx 来 处 理 海量 的 互联 网 
请 求 。Nginx 已 经 成 为 业界 高 性 能 Web 服 务 絮 的 代名词 。 


那么 ， 什 么 征 Nginx? 它 有 哪些 特点 ? 我 们 选择 Nginx 的 理由 征 什 
么 ? 如 何 编译 安装 Nginx? 这 种 安 闭 方式 痛 后 隐 汤 的 又 是 什么 样 的 思想 


呢 ? 本 章 将 会 回答 上 述 问 题 。 


1.1 Nginx 是 什么 


人 们 在 了 解 新 事物 时 ， 往 往 习 惯 通过 类 比 来 帮助 自己 理解 事物 的 
概 狐 。 那 么 ， 我 们 在 学 习 Nginx 时 也 采用 同样 的 方式 ， 先 来 看 看 Nginx 
的 竞争 对 手 一 一 Apache、Lighttpd、Tomcat、Jetty、IIS， 它 们 都 是 Web 
服务 器 ， 或 者 叫做 WWW (World Wide Web) 服务 器 ， 相 应 地 也 都 具备 
Web 服 务 器 的 基本 功能 : 基于 REST 架 构 风 格 1， 以 统一 资源 描述 符 

(Uniform Resource Identifier，URI) 或 者 统一 资源 定位 符 (Uniform 
Resource Locator，URL) 作为 沟通 依据 ， 通 过 HTTP 为 浏览 器 等 客户 端 
程序 提供 各 种 网 络 服务 。 然 而 ， 由 于 这 些 Web 服 务 器 在 设计 阶段 承受 到 
许多 局 限 ， 例 如 当时 的 互联 网 用 户 规模 、 网 络 带宽 、 产 品 特点 等 局 
限 ， 并 且 各 目的 定位 与 发 展 方向 都 不 尽 相 同 ， 使 得 每 一 款 Web 服 务 顺 的 
特点 与 应 用 场合 都 很 鲜明 。 


Tomcat 和 Jetty 面 向 Java 语 言 ， 先 天 就 是 重量 级 的 Web 服 务 器 ， 它 的 
性 能 与 Nginx 没 有 可 比 性 ， 这 里 略 过 。 


IIS 只 能 在 Windows 操 作 系 统 上 运行 。Windows 作 为 服务 全 在 稳定 性 
其 他 一 些 性 能 上 都 不 如 类 UNIX 操 作 系 统 ， 因 此 ， 在 需要 高 性 能 Web 
及 务 句 的 场合 下 ，IIS 可 能 会 修 “ 冷 落 ”。 


汝 山 


Apache 的 发 展 时 期 很 长 ， 而 且 是 目前 训 无 争议 的 世界 第 一 大 Web 服 
务 器 ， 图 1-1 中 是 12 年 来 (2010~2012 年 ) 世界 web 服务器 的 使 用 排名 情 
禹 。 
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图 1-1 ” Netcraft 对 于 644275754 个 站 点 31.4M 个 域名 Web 有 上 服务器 使 用 情况 
的 调查 结果 (2012 年 3 月 ) 


从 图 1-1 中 可 以 看 出 ，Apache 目 前 处 于 领先 地 位 。 


Apache 有 许多 优点 ， 如 稳定 、 开 源 、 跨 平台 等 ， 但 它 出 现 的 时 间 
太 长 了 ， 在 它 兴起 的 年 代 ， 互 联网 的 产业 规模 远 远 比 不 上 今天 ， 所 以 
它 被 设计 成 了 一 个 重量 级 的 、 不 文 持 高 并 发 的 Web 服 务 右 。 在 Apache 服 
务 器 上 ， 如 果 有 数 以 万 计 的 并 发 HTTP 请 求 同 时 访问 ， 就 会 导致 服务 器 
上 消耗 大 量 内 存 ， 操 作 系 统 内 核对 成 百 上 千 的 Apache 进 程 做 进程 间 切 


换 也 会 消耗 大 量 CPU 资 源 ， 并 导致 HTTP 请 求 的 平均 响应 速度 降低 ， 这 

些 都 决定 了 Apache 不 可 能 成 为 高 性 能 Web 服 务 器 ， 这 也 促使 了 Lighttpd 

和 Nginx 的 出 现 。 观 察 图 1-1 中 Nginx 成 长 的 曲线 ， 体 会 一 下 Nginx 抢 占 市 
场 时 的 “ 吊 吊 通 人 *” 吧 。 


Lighttpd 和 Nginx 一 样 ， 都 是 轻 量 级 、 高 性 能 的 Web 服 务 器 ， 欧 美的 
业界 开发 者 比较 钟爱 Lighttpd， 而 国内 的 公司 更 青睐 Nginx，Lighttpd 使 
用 得 比较 少 。 


在 了 解 了 Nginx 的 竞争 对 手 之 后 ， 相 信 大 家 对 Nginx 也 有 了 直观 感 
受 ， 下 面 让 我 们 来 正式 地 认识 一 下 Nginx 吧 。 


仿 提示 Nginx 发 首 : enginel's:Nd3in] X o 


来 自 俄罗斯 的 Igor Sysoev 在 为 Rambler Media 
(http://www.rambler.ru/ ) 工作 期 间 ， 使 用 C 语 言 开 发 了 Nginx。Nginx 
作为 web 服务器 ， 一 直 为 俄罗斯 著名 的 门户 网 站 Rambler Media 提 供 着 
出 色 、 稳 定 的 服务 。 


Igor Sysoev 将 Nginx 的 代码 开源 ， 并 且 赋 了 予 其 最 目 由 的 2-clause 
BSD-like license 2 许可 证 。 由 于 Nginx 使 用 基于 事件 张 动 的 架构 能 够 并 
发 处 理 百 万 级 别 的 TCP 连 接 ， 高 度 模块 化 的 设计 和 自由 的 许可 证 使 得 扩 
展 Nginx 功 能 的 第 三 方 模块 层出不穷 ， 而 且 优 秀 的 设计 带 来 了 极 佳 的 稳 


定性 ， 因 此 其 作为 Web 服 务 夯 被 广泛 应 用 到 大 流量 的 网 站 上 ， 包 括 腾 
讯 、 新 浪 、 网 易 、 淘 宝 等 访问 量 巨 大 的 网 站 。 


2012 年 2 月 和 3 月 Netcraft 对 Web 服 务 器 的 调查 如 表 1-1 所 示 ， 可 以 看 
出 ，Nginx 的 市 场 份额 越 来 越 大 。 


表 1-1 ” Netcraft 对 于 Web 服 务 器 市 场 占 有 率 前 4 位 软件 的 调查 (2012 年 2 
月 和 3 引 月) 


Web 服务 器 市 场 占有 率 ”| ”占有 率 变化 
Google Web Server -003 


Nginx 是 一 个 跨 平 台 的 Web 服 务 右 ， 可 运行 在 Linux、FreeBSD、 
Solaris、AIX、Mac O0S、Windows 等 操作 系统 上 ， 并 且 它 还 可 以 使 用 当 
前 操作 系统 特有 的 一 些 高 效 API 来 提高 自己 的 性 能 。 


例如 ， 对 于 高 效 处 理 大 规模 并 发 连接 ， 它 支持 Linux 上 的 epoll 
(epoll 是 Linux 上 处 理 大 并 发 网 络 连 接 的 利器 ，9.6.1 节 中 将 会 详细 说 明 
epoll 的 工作 原理 ) 、Solaris 上 的 event ports 和 FreeBSD 上 的 kqueue 等 。 


又 如 ， 对 于 Linux，Nginx 文 持 其 独 有 的 sendfile 系 统 调用 ， 这 个 系 
统 调用 可 以 高 效 地 把 硬盘 中 的 数据 发 送 到 网 络 上 (不 需要 先 把 硬盘 数 
据 复制 到 用 户 态 内 存 上 再 发 送 ) ， 这 极 大 地 减少 了 内 核 态 与 用 户 态 数 
据 间 的 复制 动作 。 


种 种 迹象 都 表明 ，Nginx 以 性 能 为 王 。 


2011 年 7 月 ，Nginx 正 式 成 立 公 司 ， 由 Igor Sysoev 担 任 CTO， 立 足 于 
提供 商业 级 的 Web 服务 器 。 


[1] 参见 Roy Fielding 博 士 的 论文 《Architectural Styles and the Design of 
Network-based Software Architectures》 ， 可 在 http:/www.ics.uci.edu/~f 
ielding/pubs/dissertation/top.htm 查 看 原文 。 

[2] BSD (Berkeley Software Distribution) 许可 协议 是 自由 软件 (开源 
软件 的 一 个 子 集 ) 中 使 用 最 广泛 的 许可 协议 之 一 。 与 其 他 许可 协议 相 
比 ，BSD 许 可 协议 从 GNU 通 用 公共 许可 协议 (GPL) 到 限制 重重 的 著 
作 权 (copyright) 都 要 宽松 一 些 ， 事 实 上 ， 它 跟 公 有 领域 更 为 接近 。 
BSD 许 可 协议 被 认为 是 copycenter (中 间 版 权 ) ， 界 于 标准 的 copyright 
与 GPL 的 copyleft 之 间 。2-clause BSD-like license 是 BSD 许 可 协议 中 最 宽 
松 的 一 种 ， 它 对 开发 者 再 次 使 用 BSD 软 件 只 有 两 个 基本 的 要 求 : 一 是 
如 果 再 发 布 的 产品 中 包含 源 代码 ， 则 在 源 代 码 中 必须 带 有 原来 代码 中 
的 BSD 协 议 ， 二 是 如 果 再 发 布 的 只 是 二 进 制 类 库 / 软 件 ， 则 需要 在 类 库 / 
软件 的 文档 和 版 权 声明 中 包含 原来 代码 中 的 BSD 协 议 。 


1.2 为 什么 选择 Nginx 


为 什么 选择 Nginx? 因为 它 具 有 以 下 特点 : 


(1) 更 快 


这 表现 在 两 个 方面 : 一 方面 ， 在 正常 情况 下 ， 单 次 请 求 会 得 到 更 
快 的 啊 应 ， 男 一 方面 ， 在 高 峰 期 (如 有 数 以 万 计 的 并 发 请 求 ) ，Nginx 
可 以 比 其 他 Web 服 务 器 更 快 地 啊 应 请 求 。 


实际 上 ， 本 书 第 三 部 分 中 大 量 的 篇 幅 都 是 在 说 明 Nginx 是 如 何 做 到 
这 两 点 的 。 


(2) 高 扩展 性 


Nginx 的 设计 极 具 扩 展 性 ， 它 完全 是 由 多 个 不 同 功能 、 不 同 层次 、 
不 同类 型 且 炎 合 度 极 低 的 模块 组 成 。 因 此 ， 当 对 某 一 个 模块 修复 Bug 
或 进行 升级 时 ， 可 以 专注 于 模块 自身 ， 无须 在 意 其 他 。 而 且 在 HTTP 模 
块 中 ， 还 设计 了 HTTP 过 滤器 模块 ， 一 个 正常 的 HTTP 模 块 在 处 理 完 请 
求 后 ， 会 有 一 串 HTTP 过 滤器 模块 对 请 求 的 结果 进行 再 处 理 。 这 样 ， 当 
我 们 开发 一 个 新 的 HTTP 模 块 时 ， 不 但 可 以 使 用 诸如 HTTP 核 心 模块 、 
events 模 块 、log 模 块 等 不 同 层次 或 者 不 同类 型 的 模块 ， 还 可 以 原封 不 
动 地 复 用 大 量 已 有 的 HTTP 过 滤器 模块 。 这 种 低 硬 合 度 的 优秀 设计 ， 造 


束 了 Nginx 庞 大 的 第 三 方 模块 ， 当 然 ， 公 开 的 第 三 方 模块 也 如 官方 发 布 
的 模块 一 样 容易 使 用 。 


Nginx 的 模块 都 是 典 入 到 二 进 制 文件 中 执行 的 ， 无 论 官 方 发 布 的 模 
块 还 是 第 三 方 模块 都 是 如 此 。 这 使 得 第 三 方 模块 一 样 具 备 极其 优秀 的 
性 能 ， 充 分 利用 Nginx 的 高 并 发 特性 ， 因 此， 许多 高 流量 的 网 站 都 倾 回 
于 开发 符合 目 己 业务 特性 的 定制 模块 。 


(3) 高 可 靠 性 


高 可 靠 性 钙 我 们 选择 Nginx 的 最 基本 条 件 ， 因 为 Nginx 的 可 徘 性 是 
大 家 有 目 共 睹 的 ， 很 多 家 高 流量 网 站 都 在 核心 服务 器 上 大 规模 使 用 
Nginx。Nginx 的 高 可 靠 性 来 目 于 其 核心 框架 代码 的 优秀 设计 、 模 块 设 
计 的 简单 性 ， 男 外 ， 官 方 提供 的 党 用 模块 都 非常 稳定 ， 每 个 worker 进 
程 相对 独立 ，master 进 程 在 1 个 worker 进 程 出 错时 可 以 快速 “ 拉 起 ”新 的 
worker 了 于 进程 提供 服务 。 


(4) 低 内 存 消耗 


一 般 情况 下 ，10000 个 非 活 路 的 HTTP Keep-Alive 连 接 在 Nginx 中 仅 
消耗 2.5MB 的 内 存 ， 这 是 Nginx 支 持 高 并 发 连接 的 基础 。 


从 第 3 章 开始 ， 我 们 会 接触 到 Nginx 在 内 存 中 为 了 维护 一 个 HTTP 连 
接 所 分 配 的 对 象 ， 届 时 将 会 看 到 ， 实 际 上 Nginx 一 直 在 为 用 户 考虑 〈 尤 


其 是 在 高 并 发 时 ) 如 何 使 得 内 存 的 消耗 更 少 。 


(5) 单机 文 持 10 万 以 上 的 并 发 连接 


这 征 一 个 非常 重要 的 特性 ! 随 着 互联 网 的 迅猛 发 展 和 互联 网 用 户 
数量 的 成 倍增 长 ， 各 大 公司 、 网 站 都 需要 应 付 海量 并 发 请 求 ， 一 个 能 
够 在 峰值 期 项 住 10 万 以 上 并 发 请 求 的 Server， 无 疑 会 得 到 大 家 的 青 
胀 。 理 论 上 ，Nginx 文 持 的 并 发 连接 上 限 取 决 于 内 存 ，10 万 远 末 封顶 。 
当然 ， 能 够 及 时 地 处 理 更 多 的 并 发 请 求 ， 是 与 业务 特点 紧密 相关 的 ， 
本 书 第 8~11 章 将 会 详细 说 明 如 何 实现 这 个 特点 。 


(6) 热 部 署 


master 管 理 进程 与 worker 工 作 进程 的 分 离 设 计 ， 使 得 Nginx 能 够 提 
供 热 部 署 功 能 ， 即 可 以 在 7x24 小 时 不 间断 服务 的 前 提 下 ， 升 级 Nginx 
的 可 执行 文件 。 当 然 ， 它 也 文 持 不 停止 服务 束 更 新 配置 项 、 更 换 日 志 
文件 等 功能 。 


(7) 最 自由 的 BSD 许 可 协议 
这 是 Nginx 可 以 快速 发 展 的 强大 动力 。BSD 许 可 协议 不 只 是 允许 用 
户 免费 使 用 Nginx， 它 还 允许 用 户 在 自己 的 项 目 中 直接 使 用 或 修改 
Nginx 源 码 ， 然 后 发 布 。 这 吸引 了 无 数 开 发 者 继续 为 Nginx 贡 献 自己 的 


未 


以 上 7 个 特点 当然 不 是 Nginx 的 全 部 ， 拥 有 无 数 个 官方 功能 模块 、 
第 三 方 功能 模块 使 得 Nginx 能 够 满足 绝 大 部 分 应 用 场景 ， 这 些 功能 模块 
间 可 以 登 加 以 实现 更 加 强大 、 复 杂 的 功能 ， 有 些 模块 还 支持 Nginx 与 
Perl、Lua 等 脚本 语言 集成 工作 ， 大 大 提高 了 开发 效率 。 这 些 特点 促使 
用 户 在 寻找 一 个 Web 服 务 器 时 更 多 考虑 Nginx 。 


当然 ， 选 择 Nginx 的 核心 理由 还 是 它 能 在 文 持 高 并 发 请 求 的 同时 保 
持 高 效 的 服务 。 


如 有 果 Web 服 务 器 的 业务 访问 量 巨 大 ， 束 需要 保证 在 数 以 百 万 计 的 
请 求 同 时 访问 服务 时 ， 用 户 可 以 获得 民 好 的 体验 ， 不 会 出 现 并 发 访问 
量 达到 一 个 数字 后 ， 新 的 用 户 无 法 获取 服务 ， 或 者 虽然 成 功 地 建立 起 
了 TCP 连 接 ， 但 大 部 分 请 求 却 得 不 到 响应 的 情况 。 


通常 ， 高 峰 期 服务 大 的 访问 量 可 能 是 正常 情况 下 的 许多 倍 ， 有 有 
热点 事件 的 发 生 ， 可 能 会 导 公 正常 情况 下 非常 顺畅 的 服务 右 直 接 “ 挂 
死 *”。 然而 ， 如 果 在 部 署 服务 器 时 ， 就 预 完 针对 这 种 情况 进行 扩容 ， 双 
会 使 得 正常 情况 下 所 有 服务 器 的 人 负载 过 低 ， 这 会 造成 大 量 的 资源 浪 
费 。 因 此 ， 我 们 会 希望 在 这 之 间 取 得 平衡 ， 也 就 是 说 ， 在 低 并 发 压力 
下 ， 用 户 可 以 获得 高 速 体验 ， 而 在 高 并 发 压力 下 ， 更 多 的 用 户 都 能 接 
入 ， 可 能 访问 速度 会 下 降 ， 但 这 只 应 受制 于 这 贺 和 处 理 右 的 速度 ， 而 
不 应 该 是 服务 器 设计 导致 的 软件 瓶颈 


事实 上 ， 由 于 中 国 互 联网 用 户 群 体 的 数量 巨大 ， 致 使 对 Web 服 务 
器 的 设计 往往 要 比 欧美 公司 更 加 困难 。 例 如 ， 对 于 全 球 性 的 一 些 网 站 
而 言 ， 欧 美 用 户 分 布 在 两 个 半球 ， 欧 洲 用 户 活跃 时 ， 美 洲 用 户 通 向 在 
休息 ， 反 之 亦 然 。 而 国内 巨大 的 用 户 群 体 则 对 业界 的 程序 员 提 出 更 高 
的 挑战 ， 早 上 9 点 和 晚上 20 点 到 24 点 这 些 时 间 段 的 并 发 请 求 压力 古 非 党 
巨大 的 。 尤 其 证 假日、 寒暑 假 到 来 之 时 ， 更 会 对 服务 右 提 出 极 高 的 要 
求 。 


另外 ， 国 内 业务 上 的 特性 ， 也 会 引导 用 户 在 同一 时 间 大 并 发 地 访 
问 服务 絮 。 例 如 ， 许 多 SNS 网 页 游戏 会 在 固定 的 时 间 点 刷新 游戏 痪 源 
或 者 允许 “ 偷 且 ” 等 好 友 互 动 操作 。 这 些 会 导致 服 务 右 处 理 高 并 发 请 求 
的 压力 增 大 。 


上 述 情 形 都 对 我 们 的 互联 网 服务 在 大 并 发 压力 下 十 否 还 能 够 给 予 
用 户 民 好 的 体验 握 出 了 更 高 的 要 求 。 寿 要 提供 更 好 的 服务 ， 那 么 可 以 
从 多 方面 入 手 ， 例 如 ， 修 改 业 务 特性 、 引 导 用 户 从 高 峰 期 分 流 或 者 把 
服务 分 层 分 级 、 对 于 不 同 并 发 压力 给 用 户 提供 不 同 级 别 的 服务 等 。 但 
最 根本 的 是 ，Web 服 务 絮 要 能 文 持 大 并 发 压力 下 的 正常 服务 ， 这 才 是 
关键 。 


快速 增长 的 互联 网 用 户 群 以 及 业内 所 有 互联 网 服务 提供 商 越 来 越 
好 的 用 户 体 验 ， 都 促使 我 们 在 大 流量 服务 中 用 Nginx 取 代 其 他 Web 服 务 
锅 。Nginx 先 天 的 事件 驱动 型 设计 、 全 异步 的 网 络 1/O 处 理 机 制 、 极 少 


的 进程 间 切 换 以 及 许多 优化 设计 ， 都 使 得 Nginx 天 生养 于 处 理 高 并 发 压 
力 下 的 互联 网 请 求 ， 同 时 Nginx 降 低 了 资源 消耗 ， 可 以 把 服务 器 硬件 资 
源 “ 庄 梅 ?到 极致 。 


1.3 ”准备 工作 


由 于 Linux 具 有 免费 、 使 用 广泛 、 商 业 文 持 越 来 越 完善 等 特点 ， 本 
书 将 主要 针对 Linux 上 运行 的 Nginx 来 进行 介绍 。 需 要 说 明 的 是 ， 本 书 
不 是 使 用 手册 ， 而 是 介绍 Nginx 作 为 Web 服 务 絮 的 设计 思想 ， 以 及 如 何 
更 有 效 地 使 用 Nginx 达 成 目的 ， 而 这 些 内 容 在 各 操作 系统 上 基本 是 相通 
的 (除了 第 9 章 关 于 事件 驱动 方式 以 及 第 14 章 的 进程 间 同 步 方 式 在 类 
UNIX 操 作 系统 上 略 有 不 同 以 外 ) 。 


1.3.1 Linux 操 作 系 统 


首先 我 们 需要 一 个 内 核 为 Linux 2.6 及 以 上 版 本 的 操作 系统 ， 因 为 
Linux 2.6 及 以 上 内 核 才 支持 epoll， 而 在 Linux 上 使 用 select 或 poll 来 解决 
事件 的 多 路 复 用 ， 是 无 法 解决 高 并 发 压力 问题 的 。 


我 们 可 以 使 用 uname-a 命 令 来 查询 Linux 内 核 版 本 ， 例 如 : 


:wehf2wng001:root > uname -a 
Linux wehf2wng001 2.6.18-128.el5 #1 SMP Wed Jan 21 10:41:14 EST 2009 x86_64 x86_64 
x86_64 GNU/Linux 


执行 结果 表明 内 核 版 本 是 2.6.18， 符 合 我 们 的 要 求 。 


1.3.2 ”使 用 Nginx 的 必 备 软件 


如 有 果 要 使 用 Nginx 的 常用 功能 ， 那 么 首先 需要 确保 该 操作 系统 上 至 
少 安息 了 如 下 软件 *% 


(1) GCC 编译 器 


GCC (GNU Compiler Collection) 可 用 来 编译 C 语 言 程 序 。Nginx 不 
会 直接 提供 二 进 制 可 执行 程序 〈1.2.x 版 本 中 已 经 开始 提供 某 些 操作 系 
统 上 的 二 进 制 安装 包 了 ， 不 过 ， 本 书 探讨 如 何 开发 Nginx 模 块 是 必须 通 
过 直接 编译 源 代 码 进行 的 ) ， 这 有 许多 原因 ， 本 章 后 面 会 详 述 。 我 们 
可 以 使 用 最 简单 的 yum 方 式 安装 GCC， 例 如 : 


yum install -y gcc 


GCC 是 必需 的 编译 工具 。 在 第 3 章 会 提 到 如 何 使 用 C++ 来 编写 Nginx 
HTTP 模 块 ， 这 时 就 需要 用 到 G++ 编 译 器 了 。G++ 编 译 器 也 可 以 用 yum 
安装 ， 例 如 : 


yum install -y gcc-ct++ 


Linux 上 有 许多 软件 安装 方式 ，yum 只 是 其 中 比较 方便 的 一 种 ， 其 
他 方式 这 里 不 再 玖 述 。 


(2) PCRE 库 


PCRE (Perl Compatible Regular Expressions，Perl 兼 容 正 则 表达 
式 ) 是 由 Philip Hazel 开 发 的 函数 库 ， 目 前 为 很 多 软件 所 使 用 ， 该 库 支 
持 正 则 表达 式 。 它 由 RegEx 演 化 而 来 ， 实 际 上 ，Perl 正 则 表达 式 也 是 源 
自 于 Henry Spencer 写 的 RegEx。 


如 果 我 们 在 配置 文件 nginx.conf 里 使 用 了 正则 表达 式 ， 那 么 在 编译 
Nginx 时 就 必须 把 PCRE 库 编译 进 Nginx， 因 为 Nginx 的 HITP 模 块 要 靠 它 
来 解析 正则 表达 式 。 当 然 ， 如 果 你 确认 不 会 使 用 正则 表达 式 ， 就 不 必 
安装 它 。 其 yum 安 装 方式 如 下 : 


yum install -y pcre pcre-devel 


pcre-deve] 是 使 用 PCRE 做 二 次 开发 时 所 需要 的 开发 库 ， 包 括 头 文件 
等 ， 这 也 是 编译 Nginx 所 必须 使 用 的 。 


(3) zlib 库 


zlib 库 用 于 对 HTTP 包 的 内 容 做 gzip 格 式 的 压缩 ， 如 果 我 们 在 
nginx.conf 里 配置 了 gzip on， 并 指定 对 于 某 些 类 型 (content-type) 的 
HTTP 响 应 使 用 gzip 来 进行 压缩 以 减少 网 络 传输 量 ， 那 么 ， 在 编译 时 就 
必须 把 zlib 编 译 进 Nginx。 其 yum 安 装 方式 如 下 : 


yum install -y zlib zlib-devel 


同 理 ，zlib 是 直接 使 用 的 库 ，zlib-devel 是 二 次 开发 所 需要 的 库 。 


(4) OpenSSL 开 发 库 


如 果 我 们 的 服务 器 不 只 是 要 支持 HTTP， 还 需要 在 更 安全 的 SSL 协 
议 上 传输 HTTP， 那 么 就 需要 拥有 OpenSSL 了 “。 另 外 ， 如 果 我 们 想 使 用 
MD5、SHA1 等 散 列 函数 ， 那 么 也 需要 安装 它 。 其 yum 安 装 方式 如 下 : 


yum install -y openssl openssl-devel 


上 面 所 列 的 4 个 库 只 是 完成 Web 服 务 器 最 基本 功能 所 必需 的 。 


Nginx 古 高 度 自由 化 的 Web 服 务 器 ， 它 的 功能 是 由 许多 模块 来 支持 
的 。 而 这 些 模块 可 根据 我 们 的 使 用 需求 来 定制 ， 如 采 某 些 模 块 不 需要 
使 用 则 完全 不 必 理 会 它 。 同 样 ， 如 末 使 用 了 某 个 模块 ， 而 这 个 模块 使 
用 了 一 些 类 似 zlib 或 OpenSSL 等 的 第 三 方 库 ， 那 么 就 必须 先 安装 这 些 软 
(人 作 


1.3.3 ”位 盘 日 好 


要 使 用 Nginx， 还 需要 在 Linux 文 件 系 统 上 准备 以 下 目录 。 


(1) Nginx 源 代码 存放 目录 


该 目录 用 于 放置 从 官网 上 下 载 的 Nginx 源 码 文 件 ， 以 及 第 三 方 或 我 
们 目 己 所 写 的 模块 源 代码 文件 。 


(2) Nginx 编 译 阶段 产生 的 中 间 文 件 存放 目录 
该 目录 用 于 放置 在 configure 命 令 执行 后 所 生成 的 源 文件 及 目录 ， 以 


及 make 命 令 执行 后 生成 的 目标 文件 和 最 终 连接 成 功 的 二 进 制 文件 。 默 
认 情 况 下 ，configure 命 令 会 将 该 目 杂 命名 为 objs， 并 放 在 Nginx 源 代码 


目录 下 。 


(3) 部 署 目录 
该 目 孙 存放 实际 Nginx 服 务 运行 期 间 所 需要 的 二 进 制 文件 、 配 置 文 
件 等 。 默 认 情 况 下 ， 该 目录 为 /usr/local/nginx 。 
(4) 日 志文 件 存放 目录 
日 志文 件 通 常会 比较 大 ， 当 研究 Nginx 的 压 层 架构 时 ， 需 要 打开 
debug 级 别 的 日 志 ， 这 个 级 别 的 日 志 非 第 详细 ， 会 叶 致 日 志文 件 的 大 小 


增长 得 极 快 ， 需 要 预先 分 配 一 个 拥有 更 大 磁盘 空间 的 目录 。 


1.3.4 ” Linux 内核 参 数 的 优化 


由 于 先 认 的 Linux 内 核 参 数 考虑 的 是 最 通用 的 场景 ， 这 明显 不 符合 
用 于 文 持 高 并 发 访问 的 web 服务 需 的 定义 ， 所 以 需要 修改 Linux 内 核 参 


数 ， 使 得 Nginx 可 以 拥有 更 高 的 性 能 。 


在 优化 内 核 时 ， 可 以 做 的 事情 很 多 ， 不 过 ， 我 们 通 闸 会 根据 业务 
特点 来 进行 调整 ， 当 Nginx 作 为 静态 Web 内 容 服 务 器 、 反 向 代理 服务 器 
或 是 提供 图 片 缩 略图 功能 〈 实 时 压缩 图 片 ) 的 服务 器 时 ， 其 内 核 参 数 
的 调整 都 是 不 同 的 。 这 里 只 针对 最 通用 的 、 使 Nginx 文 持 更 多 并 发 请 求 
的 TCP 网 络 参 数 做 简单 说 明 。 


首先 ， 修改 /etc/sysctl.conf 来 更 改 内 核 参 数 。 例 如 ， 最 常用 的 
配置 : 


fs.file-max = 999999 
net.ipv4.tcp_ tw _ reuse = 1 
net.ipv4.tcp_keepalive time = 600 
net.ipv4.tcp_fin timeout = 30 
net.ipv4.tcp_max_tw_ buckets = 5000 
net.ipv4.ip_local_port_range = 1024 61000 
net.ipv4.tcp_rmem = 4096 32768 262142 
net.ipv4.tcp_wmem = 4096 32768 262142 
net.core.netdev max_backlog = 8096 
net.core.rmem default = 262144 
net.core.wmem default = 262144 
net.core.rmem max = 2097152 
net.core.wmem max = 2097152 
net.ipv4.tcp_syncookies = 1 
net.ipv4.tcp_max_syn.backlog=1024 


然后 执行 sysctl-p 命 令 ， 使 上 述 修 改 生效 。 
上 面 的 参数 意义 解释 如 下 : 


-file-max: 这 个 参数 表示 进程 (比如 一 个 worker 进 程 ) 可 以 同时 打 
开 的 最 大 句柄 数 ， 这 个 参数 直接 限制 最 大 并 发 连接 数 ， 需 根据 实际 情 
况 配 置 。 


-tcp_tw_reuse: 这 个 参数 设置 为 1， 表 示人 允许 将 TIME-WAIT 状 态 的 
socket 重 新 用 于 新 的 TCP 连 接 ， 这 对 于 服务 器 来 说 很 有 意义 ， 因 为 服务 
器 上 总 会 有 大 量 TIME-WAIT 状 态 的 连接 。 


tcp_keepalive_time: 这 个 参数 表示 当 keepalive 局 用 时 ，TCP 发 送 
keepalive 消 息 的 频 度 。 默 认 是 2 小 时 ， 若 将 其 设置 得 小 一 些 ， 可 以 更 快 
地 清理 无 效 的 连 授 。 


tcp_fin_timeout: 这 个 参数 表示 当 服务 器 主动 关闭 连接 时 ，socket 
保持 在 FIN-WAIT2 状 态 的 最 大 时 间 。 


tcp_max_tw_buckets: 这 个 参数 表示 操作 系统 允许 TIME_WAIT 套 
接 字 数量 的 最 大 值 ， 如 果 超 过 这 个 数字 ，TIME_WAIT 套 接 字 将 立刻 被 
请 除 并 打印 警告 信息 。 该 参数 默认 为 180000， 过 多 的 TIME_WAIT 套 接 
字 会 使 Web 服 务 器 变 慢 。 


tcp_max_syn_backlog: 这 个 参数 表示 TCP 三 次 握手 建立 阶段 接收 
SYN 请 求 队列 的 最 大 长 度 ， 默 认为 1024， 将 其 设置 得 大 一 些 可 以 使 出 
现 Nginx 繁 忙 来 不 及 accept 新 连接 的 情况 时 ，Linux 丰 至 于 丢失 客户 端 发 
起 的 连接 请 求 。 


-ip_local_port_range: 这 个 参数 定义 了 在 UDP 和 TCP 连 接 中 本 地 
(不 包括 连接 的 远 端 ) 端口 的 取 值 范围 。 


net.ipv4.tcp_rmem: 这 个 参数 定义 了 TCP 接 收 缓存 (用 于 TCP 接 收 
滑动 窗口 ) 的 最 小 值 、 默 认 值 、 最 大 值 。 


mnet.ipv4.tcp_wmem: 这 个 参数 定义 了 人 TCP 发 送 缓存 (用 于 TCP 发 送 
滑动 窗口 ) 的 最 小 值 、 默 认 值 、 最 大 值 。 


mnetdev_max_backlog: 当 网 卡 接 收 数据 包 的 速度 大 于 内 核 处 理 的 速 
度 时 ， 会 有 一 个 队列 保存 这 些 数据 包 。 这 个 参数 表示 该 队列 的 最 大 
值 。 


-rmem_default， 这 个 参数 表示 内 核 套 接 字 接 收 绥 存 区 默认 的 大 小 。 


wmem_default， 这 个 参数 表示 内 核 父 接 字 发 送 缓存 区 默认 的 大 


小 。 


Tmem_max: 这 个 参数 表示 内 核 懈 接 字 接收 缓存 区 的 最 大 大 小 。 


-wmem_max: 这 个 参数 表示 内 核 套 接 子 发 送 缓存 区 的 最 大 大 小 。 


人 @@ 注意 滑动 窗 口 的 大 小 与 套 接 字 缓 存 区 会 在 一 定 程度 上 影响 
并 发 连接 的 数目 。 每 个 TCP 连 接 部 会 为 维护 TCP 渭 动 窗口 而 消耗 内 存 ， 
这 个 窗口 会 根据 服务 器 的 处 理 速度 收缩 或 扩张 。 


参数 wmem_max 的 设置 ， 需 要 平衡 物理 内 存 的 总 大 小 、Nginx 并 发 
处 理 的 最 大 连接 数量 (由 nginx.conf 中 的 worker_processes 和 


worker_connections 参 数 决定 ) 而 确定 。 当 然 ， 如 果 仅 仅 为 了 提高 并 发 
量 使 服务 器 不 出 现 Out Of Memory 问 题 而 去 降低 请 动 窗口 大 小 ， 那 么 并 
不 合适 ， 因 为 滑动 窗口 过 小 会 影响 大 数据 量 的 传输 速度 。 
rmem_default、wmem_default、rmem_max、wmem_max 文 4 个 参数 的 设 


置 需要 根据 我 们 的 业务 特性 以 及 实际 的 硬件 成 本 来 综合 考虑 。 
-tcp_syncookies: 该 参数 与 性 能 无 关 ， 用 于 解决 TCP 的 SYN 攻 击 。 
1.3.5 ”获取 Nginx 源 人 码 


可 以 在 Nginx 官 方 网 站 (http://nginx.org/en/download.html ) 获取 
Nginx 源 码 包 。 将 下 载 的 nginx-1.0.14.tar.gz 源 码 压缩 包 放 置 到 准备 好 的 
Nginx 源 代码 目录 中 ， 然 后 解压 。 例 如 : 


tar -zxvf nginx-1.0.14.tar.gz 


本 书 编写 时 的 Nginx 最 新 稳定 版 本 为 1.0.14 (如 图 1-2 所 示 ) ， 本 书 
后 续 部 分 都 将 以 此 版 本 作为 基准 。 当 然 ， 本 书 将 要 说 明 的 Nginx 核 心 代 
码 一 般 不 会 有 改动 (否则 大 量 第 三 方 模块 的 功能 就 无 法 保证 了 ) ， 即 
使 下 载 其 他 版 本 的 Nginx 源 码 包 也 不 会 影响 阅读 本 书 。 


nginx: download 
Development version 

nginx-1.1.17 pgp nginx/Windows-1.1.17 pgp 

Stable version 
nginx/Windows-1.0.14 pgep 

Legacy versions 
nginx-0.8.55 pgp nginx/Windows-0.8.55 pgp 
CHANGES-0.7 nginx-0.7.0609 pgp nginx/Windows-0.7.69 pgp 
CHANGES-0.6 
CHANGES-0.5 


CHANGES 


CHANGES-1.0 nginx-1.0.14 pgp 


nginx-0.6.39 pgp 
nginx-0.5.58 pgp 


图 1-2 ”Nginx 的 不 同 版 本 


1.4 编译 安 闻 Nginx 


安装 Nginx 最 简单 的 方式 是 ， 进 入 nginx-1.0.14 目 录 后 执行 以 下 3 行 


合 令 : 


他 


./configure 
make 
make install 


configure 命 令 做 了 大 量 的 “幕后 ”工作 ， 包 括 检测 操作 系统 内 核 和 
已 经 安装 的 软件 ， 参 数 的 解析 ， 中 间 目 录 的 生成 以 及 根据 各 种 参数 生 
成 一 些 C 源 码 文件 、Makefile 文 件 等 。 


make 命 令 根 据 configure 命 令 生 成 的 Makefile 文 件 编译 Nginx 工 程 ， 
并 生成 目标 文件 、 最 终 的 二 进 制 文件 。 


make install 命 令 根 据 configure 执 行 时 的 参数 将 Nginx 部 署 到 指定 的 
安装 目 孙 ， 包 括 相关 目录 的 建立 和 二 进 制 文件 、 配 置 文件 的 复制 。 


1.5 configure 评 解 


可 以 看 出 ，configure 命 令 至 天 重要 ， 下 文 将 详细 介绍 如 何 使 用 
configure 命 令 ， 并 分 析 configure 到 确 是 如 何 工作 鸭 ， 从 中 我 们 也 可 以 看 


1.5.1 ”configure 的 命令 参数 


使 用 help 命 令 可 以 查看 configure 包 含 的 参数 。 


./configure --help 


这 里 不 一 一 列 出 help 的 结果 ， 只 是 把 它 的 参数 分 为 了 四 大 类 型 ， 下 
面 将 会 详 述 各 类 型 下 所 有 参数 的 用 法 和 意义 。 


1. 路 径 相 关 的 参数 
表 1-2 列 出 了 Nginx 在 编译 期 、 运 行 期 中 与 路 径 相 关 的 各 种 参数 。 


表 1-2 configure 文 持 的 路 径 相 关 参 数 


参数 名 称 


--prefix=PATH 


--Sbin-path=PATH 
--Conf-path=PATH 


--error-log-path=PATH 


--pid-path=PATH 


--lock-path=PATH 


--builddir=DIR 


--wWith-perl modules path=PATH 


--wWith-perl=PATH 


--http-log-path=PATH 


--http-client-body-temp-path=PATH 


--http-proxy-temp-path=PATH 


参数 名 称 
--http-fastcgi-temp-path=PATH 
--http-uwsgi-temp-path=PATH 
--http-scgi-temp-path=PATH 


Nginx 安装 部 署 后 的 根 目录 


可 执行 文件 的 放置 路 径 

error 日 志文 件 的 放置 路 径 。error 日 志 
用 于 定位 问题 ， 可 输出 多 种 级 别 (包括 
debug 调试 级 别 ) 的 日 志 。 它 的 配置 非常 
灵活 ， 可 以 在 nginx.cont 里 配置 为 不 同 请 
求 的 日 志 并 输出 到 不 同 的 log 文件 中 。 这 
里 是 默认 的 Nginx 核心 日 志 路 径 

pid 文件 的 存放 路 径 。 这 个 文件 里 仅 以 
ASC IT 码 存 放 着 Nginx master 的 进程 ID， 
有 了 这 个 进程 ID， 在 使 用 命令 行 ( 例 如 
nginx -s reload) 通过 读 取 master 进 程 ID 
向 master 进程 发 送信 号 时 ， 才 能 对 运行 中 
的 Nginx 服务 产生 作用 

lock 文件 的 放置 路 径 

configure 执行 时 与 编译 期 间 产 生 的 临时 
文件 放置 的 目录 ,包括 产生 的 Makefile、 
C 源 文件 、 目 标 文 件 、 可 执行 文件 等 

perl module 放置 的 路 径 。 只 有 使 用 了 第 

: 方 的 perl module， 才 需要 配置 这 个 路 径 

perl binary 放置 的 路 径 。 如 果 配 置 的 Nginx 
会 执行 Perl 脚本 ， 那 么 就 必须 要 设置 此 路 径 

access 日 志 放 置 的 位 置 。 每 一 个 HTTP 
请 求 在 结束 时 都 会 记录 的 访问 日 志 

处 理 HTTP 请 求 时 如 果 请 求 的 包 体 需要 
暂时 存放 到 临时 磁盘 文件 中 ， 则 把 这 样 的 
临时 文件 放置 到 该 路 径 下 

Nginx 作 为 HTTP 反 向 代理 服务 器 时 ， 
上 游 服务 器 产生 的 HTTP 包 体 在 需要 临时 
存放 到 磁盘 文件 时 ( 详 见 12.8 节 )， 这 样 
的 临时 文件 将 放 到 该 路 径 下 


Fastcgi 所 使 用 临时 文件 的 放置 目录 
uWSGI 所 使 用 临时 文件 的 放置 目录 
SCGI 所 使 用 临时 文件 的 放置 目录 


意 : 
数 中 的 相对 目录 
置 了 --sbin-path=sbin/nginx， 那 么 
实际 上 可 执行 文件 会 被 放 到 /usr/ 
local/nginx/sbin/nginx 中 


默认 值 
默认 为 /usr/local/nginx 目录 


<prefix>/sbin/nginx 


<prefix>/conf/nginx.conf 


<prefix>/logs/error.log 


<prefix>/logs/nginx.pid 


<prefix>/logs/nginx.lock 


<nginx source path>/objs 


无 
无 


<prefix>/logs/access.log 


<prefix>/client body temp 


<prefix>/proxy_temp 


<prefix>/fastcgl_ temp 


<prefix>/uwsgl temp 


<prefix>/scgi _ temp 


注 


这 个 目标 的 设置 会 影响 其 他 参 
例如 ， 如 果 设 


2. 编 译 相关 的 参数 


表 1-3 列 出 了 编译 Nginx 时 与 编译 器 相关 的 参数 。 


表 1-3 configure 文 持 的 编译 相关 参数 


编译 参数 意 义 
--with-cc=PATH C 编译 器 的 路 径 
--with-cpp=PATH C 预 编 译 右 的 路 径 


如 果 和 希望 在 Nginx 编译 期 间 指 定 加 入 一 些 编译 选项 ， 如 指定 宏 或 者 使 用 -I 加 入 某 些 
需要 包含 的 目录 ， 参数 达成 目的 
最 终 的 二 进 制 可 执行 文件 是 由 编译 后 生成 的 目标 文件 与 一 些 第 三 方 库 链 接生 成 的 ， 
在 执行 链接 操作 时 可 能 会 需要 指定 链接 参数 ，--with-ld-opt 就 是 用 于 加 入 链接 时 的 参 
--with-ld-opt=OPTIONS | 数 。 例 如 ， 如 果 我 们 希望 将 某 个 库 链接 到 Nginx 程序 中 ， 需 要 在 这 里 加 入 --with-ld- 
opt=llibraryName -LlibraryPath， 其 中 libraryName 是 目标 库 的 名 称 ，libraryPath 则 是 日 
标 库 所 在 的 路 径 
指定 CPU 处 理 器 架构 ， 只 能 从 以 下 取 值 中 选择 : pentium 、pentiumpro 、pentium3 、 
pentium4 、athlon、opteron、sparc32、sparc64、ppc64 


--with-cc-opt=OPTIONS 


--With-cpu-opt=CPU 


依赖 软件 的 相关 参数 


表 1-4~ 表 1-8 列 出 了 Nginx 依 赖 的 党 用 软件 支持 的 参数 。 


表 1-4 PCRE 的 设置 参数 


PCRE 库 的 设置 参数 意 义 
如 果 确 认 Nginx 不 用 解析 正则 表达 式 ， 也 就 是 说 ，nginx.conf 配置 文件 中 不 会 出 
现 正 则 表达 式 ， 那 么 可 以 使 用 这 个 人参 类 


--without-pcre 


--with-pcre 强制 使 用 PCRE 库 
--with-pcre=DIR 指定 PCRE 库 的 源码 位 置 ， 在 编译 Nginx 时 会 进入 该 目录 编译 PCRE 源码 
--with-pcre-opt=OPTIONS 编译 PCRE 源码 时 希望 加 入 的 编译 选项 


表 1-5 OpenSSL 的 设置 参数 


指定 OpenSSL 库 的 源码 位 置 ， 在 编译 Nginx 时 会 进入 该 目录 编译 OpenSSL 源码 

注意 : 如 果 Web 服务 器 支持 HITPS， 也 就 是 SSL 协议 ，Nginx 要 求 必须 使 
用 OpenSSL。 可 以 访问 http://www.openssl.org/ 免费 下 载 

编译 OpenSSL 源码 时 希望 加 入 的 编译 选项 


表 1-6 原子 库 的 设置 参数 


意 义 
强制 使 用 atomic 库 。atomic 库 是 CPU 架构 独立 的 一 种 原子 操作 的 实现 。 它 支持 
以 下 体系 架构 : x86 (包括 1386 和 x86_64 )、PPC64、Sparc64 ( v9 或 更 高 版 本 ) 或 
者 安装 了 GCC 4.1.0 及 更 高 版 本 的 架构 。14.3 节 介 绍 了 原子 操作 在 Nginx 中 的 实现 


atomic 库 所 在 的 位 置 


表 1-7” 散 列 函 数 库 的 设置 参数 


OpenSSL 库 的 设置 参数 


--With-openssl=DIR. 


--With-openssl-opt=OPTIONS 


atomic (原子 ) 库 的 设置 参数 


--With-libatomic 


--wWith-libatomic=DIR. 


散 列 函 数 库 的 设置 参数 意 义 
指定 MD5 库 的 源码 位 置 ， 在 编译 Nginx 时 会 进入 该 目录 编译 MD5 源码 
--with-MD5=DIR 注意 : Nginx 源码 中 已 经 有 了 MD5 算法 的 实现 ， 如 果 没 有 特殊 需求 ， 那 么 完 
全 可 以 使 用 Nginx 自身 实现 的 MD5 算法 
--with-MD5-opt=OPTIONS 编译 MD5 源码 时 希望 加 入 的 编译 选项 
---with-MD5-asm 使 用 MDS5 的 汇编 源码 
指定 SHA1 库 的 源码 位 置 ， 在 编译 Nginx 时 会 进入 该 目录 编译 SHA1 源码 
--with-SHA1=DIR 注意 : OpenSSL 中 已 经 有 了 SHAI 算法 的 实现 。 如 果 已 经 安装 了 OpenSSL， 
那么 完全 可 以 使 用 OpenSSL 实现 的 SHA1 算法 
--with-SHA1-opt=OPTIONS 编译 SHA1 源码 时 希望 加 入 的 编译 选项 
--wWith-SHA1-asm 使 用 SHA1 的 汇编 源码 
表 1-8 ”zlib 库 的 设置 参数 
zlib 库 的 设置 参数 意 义 


指定 zlib 库 的 源码 位 置 ， 在 编译 Nginx 时 会 进入 该 日 录 编 译 zlib 源码 。 如 果 使 


--With-zlib=DIR gg ed i et 
用 了 gzip 压缩 功能 ， 就 需要 zlib 库 的 支持 


--With-zlib-opt=OPTIONS 编译 zlib 源 公 时 希望 加 入 的 编译 选项 
指定 对 特定 的 CPU 使 用 zlib 库 的 汇编 优化 功能 ， 目 前 仅 支 持 两 种 架构 : pentium 


--With-zlib-asm=CPU 
和 pentiumpro 


4. 模 块 相关 的 参数 


除了 少量 核心 代码 外 ，Nginx 完 全 是 由 各 种 功能 模块 组 成 的 。 这 些 
模块 会 根据 配置 参数 决定 日 己 的 行为 ， 因此， 正确 地 使 用 各 个 模块 非 
党 天 键 。 在 configure 的 参数 中 ， 我 们 把 它们 分 为 五 大 类 。 


-事件 模块 。 
:默认 即 编译 进入 Nginx 的 HTTP 模 块 。 
:默认 不 会 编译 进入 Nginx 的 HTTP 模 块 。 
-邮件 代理 服务 天 相关 的 mail 模 块 。 
其 他 模块 。 
(1) 事件 模块 
表 1-9 中 列 出 了 Nginx 可 以 选择 哪些 事件 模块 编译 到 产品 中 。 


表 1-9 ”configure 文 持 的 事件 模块 参数 


编译 参数 


--with-rtsig module 


--With-select module 


--Without-select module 


--wWith-poll module 


--without-poll module 


--With-aio_ module 


意 义 

使 用 rtsig module 处 理事 件 驱 动 

默认 情况 下 ，Nginx 是 不 安装 rtsig module 的 ， 即 不 会 把 rtsig module 编译 进 最 终 的 
Nginx 二 进 制程 序 中 

使 用 select module 处 理事 件 驱 动 

select 是 Linux 提供 的 一 种 多 路 复 用 机 制 ， 在 epoll 调用 没有 诞生 前 ， 例 如 在 Linux 
2.4 及 其 之 前 的 内 核 中 ，select 用 于 支持 服务 器 提 供 高 并 发 连接 

默认 情况 下 ，Nginx 是 不 安装 select module 的 ， 但 如 果 没 有 找到 其 他 更 好 的 事件 模 
块 ， 该 模块 将 会 被 安装 

不 安装 select module 

使 用 poll module 处 理事 件 驱 动 

poll 的 性 能 与 select 类 似 ， 在 大 量 并 发 连接 下 性 能 都 远 不 如 epoll。 默 认 情 况 下 ， 
Nginx 是 不 安装 poll module 的 

不 安装 poll module 

使 用 AIO 方式 处 理事 件 驱动 

注意 : 这 里 的 aio module 只 能 与 FreeBSD 操作 系统 上 的 kqueue 事件 处 理 机 制 合作 ， 
Linux 上 无 法 使 用 

默认 情况 下 是 不 安装 aio module 的 


(2) 默认 即 编译 进入 Nginx 的 HTTP 模 块 


表 1-10 列 出 了 


\ 认 束 会 编译 进 Nginx 的 核心 HTTP 模 块 ， 以 及 如 何 把 


这 些 HTTP 模 块 从 产品 中 去 除 。 


表 1-10 ”configure 中 默认 编译 到 Nginx 中 的 HTTP 模 块 参数 


默认 安装 的 HTTP 模块 


--without-http_charset module 


--without-http_gzip_module 


--without-http_ssi module 


--without-http_userid module 


--without-http_access_ module 


--without-http_auth basic module 


--Without-http_autoindex _ module 


--without-http_geo_module 


意 义 
不 安装 http charset module。 这 个 模块 可 以 将 服务 顺 发 出 的 HITP 响应 
重 编码 
不 安装 http gzip module。 在 服务 器 发 出 的 HTTP 响应 包 中 ， 这 个 模块 
可 以 按照 配置 文件 指定 的 content-type 对 特定 大 小 的 HTTP 响应 包 体 执行 
gzip 压缩 
不 安装 http ssi module。 该 模块 可 以 在 向 用 户 返 回 的 HTTP 响应 包 体 中 
加 入 特定 的 内 容 ， 如 HTML 文件 中 国定 的 页 头 和 页 尾 
不 安装 http userid module。 这 个 模块 可 以 通过 HTTP 请 求 头 部 信息 里 的 
- 些 字段 认证 用 户 信息 ， 以 确定 请 求 是 否 合 法 
不 安装 http access module。 这 个 模块 可 以 根据 他 地 址 限制 能 够 访问 服 
务 顺 的 客户 端 
不 安装 http auth basic module。 这 个 模块 可 以 提供 最 简单 的 用 户 名 / 密 
码 认证 
不 安装 http autoindex module。 该 模块 提供 简单 的 目录 浏览 功能 
不 安装 http geo module。 这 个 模块 可 以 定义 一 些 变 量 ， 这些 变量 的 值 将 
与 客户 端 ITP 地 址 关联 ， 这 样 Nginx 针对 不 同 的 地 区 的 客户 端 (根据 IP 
地 址 判断 ) 返回 不 一 样 的 结果 ,例如 不 同 地 区 显示 不 同 语言 的 网 页 


默认 安装 的 HTTP 模块 


--wWithout-http_ map_ module 


--Without-http_split_clients module 


--Without-http_referer module 


--Without-http_rewrite module 


--Without-http_proxy_module 
--Without-http_fastcgi module 
--without-http_uwsgi module 


--without-http_scgi module 


--without-http_ memcached module 


--wWithout-http limit zone _ module 


--without-http_limit_req_module 


--without-http_empty_gif_ module 


--Without-http_browser module 


--without-http upstream ip_ hash module 


( 续 ) 


意 义 

不 安装 http map module。 这 个 模块 可 以 建立 一 个 key/value 映射 表 ， 不 
同 的 key 得 到 相应 的 value， 这 样 可 以 针对 不 同 的 URL 做 特殊 处 理 。 例 
如 ， 返 回 302 重 定向 响应 时 ， 可 以 期 望 URL 不 同时 返回 的 Location 字段 
也 不 一 样 

不 安装 http split client module。 该 模块 会 根据 客户 端的 信息 ， 例 如 了 P 
地 址 、header 头 、cookie 等 ， 来 区 分 处 理 

不 安装 http referer module。 该 模块 可 以 根据 请 求 中 的 referer 字段 来 拒 
绝 请 求 

不 安装 http rewrite module。 该 模块 提供 HTTP 请 求 在 Nginx 服务 内 部 
的 重 定向 功能 ,依赖 PCRE 库 

不 安装 http proxy module。 该 模块 提供 基本 的 HTTP 反 向 代理 功能 

不 安装 http fastcgi module。 该 模块 提供 FastCGI 功能 

不 安装 http uwsgi module。 该 模块 提供 uWSGI 功能 

不 安装 http scgi module。 该 模块 提供 SCGI 功能 

不 安装 http memcached module。 该 模块 可 以 使 得 Nginx 直接 由 上 游 的 
memcached 服务 读 取 数据 ， 并 简单 地 适 配 成 HTTP 响应 返回 给 客户 端 

不 安装 http limit zone module。 该 模块 针对 某 个 IP 地址 限制 并 发 连接 
数 。 例 如 ,使 Nginx 对 一 个 IP 地 址 仅 允 许 一 个 连接 

不 安装 http limit req module。 该 模块 针对 某 个 IP 地 址 限制 并 发 请 求 数 

不 安装 http empty gif module。 该 模块 可 以 使 得 Nginx 在 收 到 无 效 请 求 
时 ， 立 刻 返 回 内 存 中 的 1 x 1 像素 的 GIF 图 片 : 这 种 好 处 在 于 ， 对 于 明显 
的 无 效 请 求 不 会 去 试图 浪费 服务 器 资源 

不 安装 http browser module。 该 模块 会 根据 HTTP 请 求 中 的 user-agent 
字段 (该 字段 通常 由 浏览 器 填写 ) 来 识别 浏览 器 

不 安装 http upstream ip hash module。 该 模块 提供 当 Nginx 与 后 端 server 
建立 连接 时 ,会 根据 IP 做 散 列 运算 来 决定 与 后 端 哪 台 server 通信 ， 这 样 
可 以 实现 负载 均衡 


(3) 默认 不 会 编译 进入 Nginx 的 HTTP 模 块 


表 1-11 列 出 了 默认 不 会 编译 至 Nginx 中 的 HTTP 模 块 以 及 把 它们 加 入 


产 吕 中 的 方法 


表 1-11 configure 中 默认 不 会 编译 到 Nginx 中 的 HTTP 模 块 参数 


可 选 的 HTTP 模块 


--With-http ssl module 


--with-http_realip _ module 


--with-http_addition module 


意 义 


安装 http ssl module。 该 模块 使 Nginx 支持 SSL 协议 ,提供 HTTPS 服务 
注意 : 该 模块 的 安装 依赖 于 OpenSSL 开源 软件 ， 即 首先 应 确保 已 经 在 之 前 


的 参数 中 配置 了 OpenSSL 


安装 http realip module。 该 模块 可 以 从 客户 端 请 求 里 的 header 信息 (如 
X-Real-IP 或 者 X-Forwarded-For) 中 获取 真正 的 客户 端 IP 地址 


安装 http addtion module 
尾部 增加 内 容 


该 模块 可 以 在 返回 客户 端的 HTTP 包 体 头 部 或 者 


可 选 的 HTTP 模块 


--wWith-http Xslt module 


--With-http_ image filter_ module 


—with-http_geoip module 


--with-http sub module 


—with-http_dav_module 


--with-http_flv_ module 


-with-http_mp4 module 


-with-http_gzip_static_module 


—with-http_random_index_module 


-with-http_secure link module 


-with-http_degradation module 


--with-http_stub_status_module 


--with-google_perfiools module 


( 续 ) 


意 义 

安装 http xslt module。 这 个 模块 可 以 使 XML 格式 的 数据 在 发 给 客户 端 前 加 
入 XSL 泻 染 

注意 ; 这 个 和 模块 依赖 于 libxml2 和 libxslt 库 ， 安 装 它 前 首先 确保 上 述 两 个 
软件 已 经 安装 

安装 http image_filter module。 这 个 模块 将 符合 配置 的 图 片 实时 压缩 为 指定 
大 小 (widthyheight) 的 缩 略 图 再 发 送 给 用 户 ， 目 前 支持 JPEG ,PNG ,GIF 格式 

注意 : 这 个 模块 依赖 于 开源 的 libgd 库 ， 在 安装 前 确保 操作 系统 已 经 安装 了 
libed 

安装 http geoip module。 该 模块 可 以 依据 MaxMind GeolP 的 IP 地 址 数据 库 
对 客户 端的 IP 地 址 得 到 实际 的 地 理 位 置信 息 

注意 ; 该 库 依 吏 于 MaxMind GeolP 的 库 文件 ， 可 访问 http://geolite.maxmind. 
com/download/geoip/database/GeoLiteCity.dat.gz 获取 

安装 http sub module。 该 模块 可 以 在 Nginx 返回 客户 端的 HTTP 响应 包 中 
将 指定 的 字符 串 蔡 换 为 自己 需要 的 字符 串 

例如 ， 在 HTML 的 返回 中 ， 将 <head> 替换 为 </head><script language="javascript" 
src="S$script"></script> 

安装 http dav module。 这 个 模块 可 以 让 Nginx 支持 Webdav 标准 ， 如 支持 
Webdav 协议 中 的 PUT、DELETE 、COPY 、MOVE 、MKCOL 等 请 求 

安装 http flv module。 这 个 模块 可 以 在 向 客户 端 返 回响 应 时 ， 对 ELV 格式 
的 视频 文件 在 header 头 做 一 些 处 理 ， 使 得 客户 端 可 以 观看 、 拖 动 FLV 视频 

安装 http mp4 module- 该 模块 使 客户 端 可 以 观看 、 拖 动 MP4 视频 

安装 http gzip static module- 如 果 采 用 gzip 模块 把 一 些 文档 进行 gzip 格式 
压缩 后 再 返回 给 客户 端 ， 那么 对 同一 个 文件 每 次 都 会 重新 压缩 ， 这 是 比较 消 
杯 服 务 器 CPU 资源 的 。gzip static 模块 可 以 在 做 gzip 压缩 前 ， 先 查看 相同 位 
置 是 否 有 已 经 做 过 gzip 压缩 的 .gz 文件， 如 果 有 、， 就 直接 返回 - 这 样 就 可 以 
预先 在 服务 器 上 做 好 文档 的 压缩 ， 给 CPU 减负 

安装 http random index module。 该 模块 在 客户 端 访问 某 个 目录 时 ， 随 机 返 
回 该 目录 下 的 任意 文件 

安装 http secure link module。 该 模块 提供 一 种 验证 请 求 是 否 有 效 的 机 制 。 
例如 ， 它 会 验证 URL 中 需要 加 入 的 token 参数 是 否 届 于 特定 客户 端 发 来 的 ， 
以 及 检查 时 间 蕉 是 否 过 期 

安装 http degradation module。 该 模块 针对 一 些 特殊 的 系统 调用 (如 sbrk) 
做 一 些 优化 ， 如 直接 返回 HTTP 响应 码 为 204 或 者 444。 目 前 不 支持 Linux 
系统 

安装 http stub status module。 该 模块 可 以 让 运行 中 的 Nginx 提供 性 能 统计 
页 面 ， 获 取 相 关 的 并 发 连接 、 请 求 的 信息 (14.2.1 节 中 简单 介绍 了 该 模块 的 
原理 ) 

安装 google perftools module。 该 模块 提供 Google 的 性 能 测试 工具 


(4) 邮件 代理 服务 器 相关 的 mail 模 块 


表 1-12 列 出 了 把 邮件 模块 编译 到 产品 中 的 参数 。 


表 1-12 ”configure 提 供 的 邮件 模块 参数 


可 选 的 mail 模块 意 义 

安装 邮件 服务 器 反 向 代理 模块 ， 使 Nginx 可 以 反 向 代理 IMAP、POP3、SMTP 
等 协议 。 该 模块 默认 不 安装 

安装 mail ssl module。 该 模块 可 以 使 IMAP、POP3、SMTP 等 协议 基于 SSL/ 
TLS 协议 之 上 使 用 。 该 模块 默认 不 安装 并 依赖 于 OpenSSL 库 

不 安装 mail pop3 module。 在 使 用 --with-mail 参数 后 ，pop3 module 是 默认 安 
装 的 ， 以 使 Nginx 支持 POP3 协议 

不 安装 mail imap module。 在 使 用 --with-mail 参数 后 ，imap module 是 默认 安 
装 的 ， 以 使 Nginx 支持 IMAP 

不 安装 mail smtp module。 在 使 用 --with-mail 参数 后 ，smtp module 是 默认 安 
装 的 ， 以 使 Nginx 支持 SMTP 


--with-mail 
--With-mail ssl module 
--without-mail pop3_module 
--Without-malil imap module 


--without-mail_smtp_module 


5. 其 他 参数 


N 


configure 还 接收 一 些 其 他 参数 ， 表 1-13 中 列 出 了 相关 参数 的 说 明 。 


表 1-13 ”configure 提 供 的 其 他 参数 


其 他 一 些 参数 意 义 

将 Nginx 需要 打印 debug 调试 级 别 日 志 的 代码 编译 进 Nginx。 这 样 可 以 在 Nginx 运行 
时 通过 修改 配置 文件 来 使 其 打印 调试 日 志 ， 这 对 于 研究 、 定 位 Nginx 问题 非常 有 帮助 

当 在 Nginx 里 加 入 第 三 方 模块 时 ， 通 过 这 个 参数 指定 第 三 方 模块 的 路 径 。 这 个 参数 将 
在 下 文 如 何 开 发 HTTP 模块 时 使 用 到 


--With-debusg 


--add-module=PATH 


--without-http 禁用 HTTP 服务 器 

--without-http-cache 的 用 HTTP 服务 器 里 的 缓存 Cache 特性 

--with-file-aio 启用 文件 的 异步 VO 功能 来 处 理 磁盘 文件 ， 这 需要 Linux 内 核 支持 厚生 的 异步 IO 

--with-ipv6 使 Nginx 支持 IPV6 
指定 Nginx worker 进程 运行 时 所 属 的 用 户 

--UseI=USER 了 意 : 不 要 将 启动 worker 进程 的 用 户 设 为 Toot， 在 worker 进程 出 问题 时 master 进程 
要 具备 停止 / 启动 worker 进程 的 能 力 

--group=GROUP 指定 Nginx worker 进程 运行 时 所 属 的 组 


1.5.2 ”configure 执 行 流 程 


我 们 看 到 configure 命 令 文 持 非 常 多 的 参数 ， 读 者 可 能 会 好 奇 它 在 执 
行 时 到 底 做 了 哪些 事情 ， 本 节 将 通过 解析 configure 源 码 来 对 它 有 一 个 感 
性 的 认识 。configure 由 Shell 脚 本 编写 ， 中 间 会 调用 <nginx-source>/auto/ 
目录 下 的 脚本 。 这 里 将 只 对 configure 脚 本 本 号 做 分 析 ， 对 于 它 所 调用 的 
auto 目 录 下 的 其 他 工具 脚本 则 只 做 功能 性 的 说 明 。 


configure 脚 本 的 内 容 如 下 : 


#!/bin/sh 
# Copyright (C) Igor Sysoev 
# Copyright (C) Nginx, Inc. 
#auto/options 脚 本 处 理 


configure 命 令 的 参数 。 例 如 ， 如 果 参 数 是 


--help， 那 么 显示 支持 的 所 有 参数 格式 。 


options 脚 本 会 定义 后 续 工 作 将 要 用 到 的 变量 ， 然 后 根据 本 次 参数 以 及 默认 值 设置 这 些 变 量 


. auto/options 


#auto/init 脚 本 初始 化 后 续 将 产生 的 文件 路 径 。 例 如 ， 


Makefile、 


ngx_modules .c 等 文件 默认 情况 下 将 会 在 


<nginx-source>/objs/ 
. auto/init 
#auto/sources 脚 本 将 分 析 


Nginx 的 源码 结构 ， 这 样 才能 构造 后 续 的 


Makefile 文 件 


. Auto/sources 
# 编 译 过 程 中 所 有 目标 文件 生成 的 路 径 由 一 


builddir=DIR 参 数 指定 ， 默 认 情 况 下 为 


<nginx-source>/objs， 此 时 这 个 目录 将 会 被 创建 


test -d $NGX_0BJS || mkdir $NGX_OBJS 
# 开 始 准备 建立 


ngx_auto_headers.h、 


autoconf ,err 等 必要 的 编译 文件 


echo > $NGX_AUTO_HEADERS_H 
echo > $NGX_AUTOCONF_ERR 
# 疝 


objs/ngx_auto_config.h 写 入 命令 行 带 的 参数 


echo "#define NGX_ CONFIGURE \"$NGX_CONFIGURE\"" > $NGX AUTO_CONFIG H 
# 判 靳 


DEBUG 标 志 ， 如 果 有 ， 那 么 在 


objs/ngx_auto_config.h 文 件 中 写 入 


DEBUG 安 


if [ $NGX_DEBUG = YES ]; then 
have=NGX_DEBUG . auto/have 

fi 

# 现 在 开始 检查 操作 系统 参数 是 否 支 持 后 续 编 译 


Wt 


If test -z "$NGX_PLATFORM"; then 
echo "checking for 0S" 
NGX_SYSTEM= uname -s 2>/dev/null. 
NGX_RELEASE= uname -r 2>/dev/null. 
NGX_MACHINE= “uname -m 2>/dev/null. 
# 屏 幕 上 输出 


0S 名 称 、 内 核 版 本 、 


32 位 


/64 位 内 核 


echo " + $NGX_SYSTEM $NGX_ RELEASE $NGX_MACHINE" 
NGX_PLATFORM="$NGX_SYSTEM: $NGX_RELEASE: $NGX_MACHINE"; 
case "$NGX_SYSTEM" in 
MINGW32_*) 
NGX_PLATFORM=win32 
77 
esac 
else 
echo "building for $NGX_PLATFORM" 
NGX_SYSTEM=$NGX_PLATFORM 
fi 
# 检 查 并 设置 编译 器 ， 如 


GCC 是 否 安装 、 
GCC 版 本 是 否 支 持 后 续 编 译 
nginx 

auto/cc/conf 


# 对 非 
Windows 操 作 系统 定义 一 些 必要 的 头 文件 ， 


证 
| 
[a 


伶 查 其 是 否 存在 ， 以 此 决 


configure 后 续 步 又 是 否 可 以 成 功 


[1] 

if [ "$NGX_PLATFORM" != win32 ]; then 
. auto/headers 

fi 


n 


# 对 于 当前 操作 系统 ， 定 义 一 些 特定 的 操作 系统 相关 的 方法 并 检查 当前 环境 是 否 支持 。 例 如 ， 对 了 


pe 


Linux， 在 这 里 


Bu 


sched_setaffinity 设 置 进程 优先 级 ， 使 月 
Linux 特 有 的 


sendfile 系 统 调用 来 加 速 向 网 络 中 发 送 文 件 块 


. auto/os/conf 
# 定 义 类 


UNIX 操作 系统 中 通用 的 头 文件 和 系统 调用 等 ， 并 检查 当前 环境 是 否 文 持 


If [ "$NGX_PLATFORM" != win32 ]; then 
. Aauto/unix 

fi 

# 最 核心 的 构造 运行 期 


modules 的 脚本 。 它 将 会 生成 


ngx_modules .c 文 件 ， 这 个 文件 会 被 编译 进 


情 就 是 定义 了 


二 


Nginx 中 ， 其 中 它 所 做 的 唯一 的 寻 


ngx_modules 数 组 。 
ngx_modules 指 明 
Nginx 运 行 期 间 有 哪些 模块 会 参与 到 请 求 的 处 理 中 ， 包 括 

HTTP 请 求 可 能 会 使 用 哪些 模块 处 理 ， 因 此 ， 它 对 数组 元 素 的 顺序 非常 敏感 ， 也 就 是 说 ， 绝 大 部 分 模块 在 
例如 ， 一 个 请 求 必 须 先 执行 


ngx_modules 数 组 中 的 顺序 其 实 是 固定 的 


o 


ngx_http_gzip_filter_module 模 块 重新 修改 


HTTP 响 应 中 的 头 部 后 ， 才 能 使 


ngx_http_header_filter 模 块 按 昭 


headers_in 结 构 体 里 的 成 员 构 造 出 以 
TCP 流 形式 发 送 给 客户 端的 
HTTP 响 应 头 部 。 注 意 ， 我 们 在 


--add-module= 参 数 里 加 入 的 第 三 方 模块 也 在 此 步骤 写 入 到 


ngx_modules .c 文 件 中 了 


auto/modules 
#conf 脚 本 用 来 检查 


Nginx 在 链接 期 间 需 要 链接 的 第 三 方 静 态 库 、 动 态 库 或 者 目标 文件 是 否 存 在 


. auto/lib/conf 
# 处 理 


Nginx 安 装 后 的 路 径 


case ".$NGX_PREFIX" in 


NGX_PREFIX=${NGX_PREFIX: -/usr/local/nginx} 


have=NGX_PREFIX value="\"$NGX PREFIX/\"" . auto/define 
7 7 
.!) 
NGX_PREFIX= 
7 7/ 
have=NGX_PREFIX value="\"$NGX PREFIX/\"" . auto/define 
7 7 
esac 
# 处 理 
Nginx 安 装 后 


conf 文 件 的 路 径 


If [ ".$NGX_CONF_PREFIX" != "." ]; then 

have=NGX_CONF_PREFIX value="\"$NGX CONF_PREFIX/\"" . auto/define 
fi 
# 处 理 


Nginx 安 装 后 ， 二 进 制 文件 、 


pid、 


lock 等 其 他 文件 的 路 径 可 参见 


configure 参 数 中 路 径 类 选项 的 说 明 


have=NGX_SBIN_ PATH value="\"$NGX_ SBIN_PATH\"" . auto/define 
have=NGX_CONF_PATH value="\"$NGX CONF_PATH\"" . auto/define 
have=NGX_PID_PATH value="\"$NGX_ PID_ PATH\"" . auto/define 
have=NGX_LOCK_PATH value="\"$NGX LOCK_PATH\"" . auto/define 
have=NGX_ERROR_LOG_ PATH value="\"$NGX_ ERROR_LOG PATH\"" . auto/define 
have=NGX_HTTP_LOG_PATH value="\"$NGX_HTTP_LOG_ PATH\"" . auto/define 


have=NGX_HTTP_CLIENT_TEMP_PATH value="\"$NGX_ HTTP_CLIENT_TEMP_PATH\"" 

auto/define 

have=NGX_HTTP_PROXY_TEMP_PATH value="\"$NGX_ HTTP_PROXY_TEMP_PATH\"" . auto/define 
have=NGX_HTTP_FASTCGI_TEMP_PATH value="\"$NGX_HTTP_FASTCGI_TEMP_PATH\"" 
auto/define 

have=NGX_HTTP_UWSGI_TEMP_PATH value="\"$NGX_ HTTP_UWSGI_TEMP_PATH\"" . auto/define 


have=NGX_HTTP_SCGI_TEMP_PATH value="\"$NGX_HTTP_SCGI_TEMP_PATH\"" 
# 创 建 编译 时 使 用 的 


objs/Makefile 文 件 


T 


. auto/make 


# 为 


objs/Makefile 加 入 需要 连接 的 第 三 方 静态 库 、 动 态 库 或 者 目标 文件 


. auto/lib/make 
# 为 


objs/Makefile 加 入 


install 功 能 ， 当 执行 


make install 时 将 编译 生成 的 必要 文件 复制 到 安装 路 径 ， 建 立 必 要 的 目录 


. auto/install 


# 在 


ngx_auto_config.h 文 件 中 加 入 


NGX_SUPPRESS_WARN 宏 、 


NGX_SMP 安 


. auto/stubs 
# 在 


ngx_auto_config.h 文 件 中 指定 
NGX_USER 和 


NGX_GROUP 宏 ， 如 果 执 行 


configure 时 没有 参数 指定 ， 默 认 两 者 丝 为 


nobody (也 就 是 默认 以 


nobody 用 户 运 行进 程 ) 


have=NGX_USER value="\"$NGX_USER\"" . auto/define 
have=NGX_GROUP value="\"$NGX GROUP\"" . auto/define 
# 显 示 


configure 执 行 的 结果 ， 如 果 失 败 ， 则 给 出 原因 


. auto/summary 


. auto/define 


( 注 : 在 conf igure 脚 本 里 检查 某 个 特性 是 否 存在 时 ， 会 生成 一 个 
最 简单 的 只 包含 main 函 数 的 C 程 序 ， 该 程序 会 包含 相应 的 头 文件 。 然 
后 ， 通 过 检查 是 否 可 以 编译 通过 来 确认 特性 是 否 文 持 ， 并 将 结果 记录 
在 objs/autoconf.err 文 件 中 。 后 续 检查 头 文件 、 检 查 特 性 的 脚本 都 用 了 类 
似 的 方法 。) 


1.5.3 ”configure 生 成 的 文件 


当 configure 执 行 成 功 时 会 生成 objs 目 录 ， 并 在 该 日 录 下 产生 以 下 目 
录 和 文件 : 


--ngx_auto_headers ,h 
--autoconf ,err 
--ngx_auto_config.h 
--ngx_modules.c 
--Src 

|---core 

---event 

|---modules 


| 

| 

| 

| 

| p 

| |---modules 
加 es 
上 述 目录 和 文件 介绍 如 下 。 


1) src 目 录用 于 存放 编译 时 产生 的 目标 文件 。 


2) Makefile 文 件 用 于 编译 Nginx 工 程 以 及 在 加 入 install 参 数 后 安装 
Nginx° 


3) autoconf.err 保 存 configure 执 行 过 程 中 产生 的 结果 。 


4) ngx_auto_headers.h 和 ngx_auto_config.h 保 存 了 一 些 宏 ， 这 两 个 
头 文 件 会 被 src/core/ngx_config.h 及 src/os/unix/ngx_linux_config.h 文 件 
(可 将 “linux” 奉 换 为 其 他 UNIX 操 作 系 统 ) 引用 。 


5) ngx_modules.c 是 一 个 关键 文件 ， 我 们 需要 看 看 它 的 内 部 结构 。 
一 个 默认 配置 下 生成 的 ngx_modules.c 文 件 内 容 如 下 : 


#include <ngx_config.h> 
#include <ngx_core.h>... 


ngx_module t *ngx_modules[] = { 
&ngx_core_module, 
&ngx_errlog_module, 
&ngx_conf_module, 
&ngx_events_ module, 
&ngx_event_core_ module, 
&ngx_epoll_module, 
&ngx_http_module, 
&ngx_http_core module, 
&ngx_http_log_module, 
&ngx_http_upstream module, 
&ngx_http_static module, 
&ngx_http_autoindex_module, 
&ngx_http_index_module, 
&ngx_http_auth_basic module, 
&ngx_http_access module, 
&ngx_http_limit_ zone_module, 
&ngx_http_limit_req_module, 
&ngx_http_geo_module, 
&ngx_http_map_module, 
&ngx_http_split_clients_ module, 
&ngx_http_referer_ module, 
&ngx_http_rewrite_ module, 
&ngx_http_proxy_module, 
&ngx_http_fastcgi_module, 
&ngx_http_uwsgi_module, 
&ngx_http_scgi_module, 
&ngx_http_memcached_module, 


&ngx_http_empty_gif_module, 
&ngx_http_browser_module, 
&ngx_http_upstream_ip_hash_module, 
&ngx_http_write_ filter_module, 
&ngx_http_header_filter_ module, 
&ngx_http_chunked_filter_module, 
&ngx_http_range_header_filter_module, 
&ngx_http_gzip_filter_module, 
&ngx_http_postpone_filter_module, 
&ngx_http_ssi _ filter_module, 
&ngx_http_charset_filter_module, 
&ngx_http_userid filter_module, 
&ngx_http_headers_filter_module, 
&ngx_http_copy_filter_module, 
&ngx_http_range_body_filter_module, 
&ngx_http_not_modified_filter_module, 
NULL 


ngx_modules.c 文 件 就 是 用 来 定义 ngx_modules 数 组 的 。 


ngx_modules 是 非常 关键 的 数组 ， 它 指明 了 每 个 模块 在 Nginx 中 的 
优先 级 ， 当 一 个 请 求 同 时 符合 多 个 模块 的 处 理 规则 时 ， 将 按照 它们 在 
ngx_modules 数 组 中 的 顺序 选择 最 靠 前 的 模块 优先 处 理 。 对 于 HTTP 过 
滤 模 块 而 言 则 是 相反 的 ， 因 为 HTTP 框 架 在 初始 化 时 ， 会 在 
ngx_modules 数 组 中 将 过 滤 模 块 按 先后 顺序 向 过 滤 链 表 中 添加 ， 但 每 次 
都 是 添加 到 链表 的 表 头 ， 因 此 ， 对 HTTP 过 滤 模 块 而 言 ， 在 
ngx_modules 数 组 中 越 是 靠 后 的 模块 反而 会 首先 处 理 HITP 响 应 (参见 
第 6 章 及 第 11 章 的 11.9 节 ) 。 


因此 ，ngx_modules 中 模块 的 先后 顺序 非常 重要 ， 不 正确 的 顺序 会 
导致 Nginx 无 法 工作 ， 这 是 auto/modules 脚 本 执行 后 的 结果 。 读 者 可 以 
体会 一 下 上 面 的 ngx_modules 中 同一 种 类 型 下 〈 第 8 章 会 介绍 模块 类 


型 ， 第 10 章 、 第 11 章 将 介绍 的 HTTP 框 架 对 HTTP 模 块 的 顺序 是 最 敏感 
的 ) 各 个 模块 的 顺序 以 及 这 种 顺序 带 来 的 意义 。 


可 以 看 出 ， 在 安装 过 程 中 ，configure 做 了 大 量 的 幕后 工作 ， 我 们 需 
要 关注 在 这 个 过 程 中 Nginx 做 了 哪些 事情 。configure 除 了 寻找 依赖 的 软 
件 外 ， 还 针对 不 同 的 UNIX 操 作 系 统 做 了 许多 优化 工作 。 这 二 Nginx 跨 
平台 的 一 种 具体 实现 ， 也 体现 了 Nginx 追 求 高 性 能 的 一 贯 风格 。 


configure 除 了 生成 Makefile 外 ， 还 生成 了 ngx_modules.c 文 件 ， 它 决 
定 了 运行 时 所 有 模块 的 优先 级 (在 编译 过 程 中 而 不 是 编码 过 程 中 ) 。 
对 于 不 需要 的 模块 ， 既 不 会 加 入 ngx_modules 数 组 ， 也 不 会 编译 进 
Nginx 产 品 中 ， 这 也 体现 了 轻 量 级 的 概念 。 


[1] 在 configure 脚 本 里 检查 某 个 特性 是 否 存 在 时 ， 会 生成 一 个 最 简单 的 
只 包含 main 函 数 的 C 程 序 ， 该 程序 会 包含 相应 的 头 文件 。 然 后 ， 通 过 检 
查 是 否 可 以 编译 通过 来 确认 竺 性 是 否 文 择 ， 并 将 结果 记录 在 
objs/autoconf.err 文 件 中 。 后 续 检 查 头 文件 、 检 查 特 性 的 脚本 都 用 了 类 似 
的 方法 。 


1.6 Nginx 的 命令 行 控制 


在 Linux 中 ， 需 要 使 用 命令 行 来 控制 Nginx 服 务 器 的 启动 与 停止 、 
重 载 配置 文件 、 回 滚 日 志文 件 、 平 滑 升 级 等 行为 。 默 认 情 况 下 ，Nginx 
被 安装 在 目录 /usr/local/nginx/ 中 ， 其 二 进 制 文件 路 径 
为 /usr/local/nginc/sbin/nginx， 配 置 文件 路 径 
为 /usr/local/nginx/conf/nginx.conf。 当 然 ， 在 configure 执 行 时 是 可 以 指 
定 把 它们 安装 在 不 同 目 孙 的 。 为 了 简单 起 见 ， 本 节 只 说 明 默认 安装 情 
况 下 的 命令 行 的 使 用 情况 ， 如 果 读 者 安装 的 目录 发 生 了 变化 ， 那 么 蔡 
换 一 下 即 可 。 


(1) 默认 方式 启动 
直接 执行 Nginx 二 进 制程 序 。 例 如 : 
/usr/local/nginx/sbin/nginx 
这 时 ， 会 读 取 默认 路 径 下 的 配置 广 
件 : /usr/local/nginx/conf/nginx.conf 。 


实际 上 ， 在 没有 显 式 指定 nginx.conf 配 置 文件 路 径 时 ， 将 打开 在 
configure 命 令 执行 时 使 用 --conf-path=PATH 指 定 的 nginx.conf 文 件 ( 参 


见 1.5.1 节 ) 


(2) 另行 指定 配置 文件 的 启动 方式 
使 用 -c 参 数 指定 配置 文件 。 例 如 : 


/usr/local/nginx/sbin/nginx -c /tmp/nginx.conf 


这 时 ， 会 读 取 -c 参 数 后 指定 的 nginx.conf 配 置 文件 来 启动 Nginx。 


了 指定 安 闭 目 孙 的 局 动 方式 
使 用 -p 参 数 指定 Nginx 的 安装 目录 。 例 如 : 


/usr/local/nginx/sbin/nginx -p /usr/local/nginx/ 


(4) 男 行 指 定 全 局 配置 项 的 启动 方式 


可 以 通过 -g 参 数 临 时 指定 一 些 全 局 配置 项 ， 以 使 新 的 配置 项 生 
效 。 例 如 : 


/usr/local/nginx/sbin/nginx -g "pid /var/nginx/test.pid;" 


上 面 这 行 命令 意味 着 会 把 pid 文 件 写 到 /var/nginx/test.pid 中 。 


-g 参 数 的 约束 条 件 是 指定 的 配置 项 不 能 与 默认 路 径 下 的 nginx.conf 
中 的 配置 项 相 冲 突 ， 否 则 无 法 启动 。 就 像 上 例 那 样 ， 类 似 这 样 的 配置 
项 : pid logs/nginx.pid， 是 不 能 存在 于 默认 的 nginx.conf 中 的 。 


另 一 个 约束 条 件 是 ， 以 -8 方式 局 动 的 Nginx 服 务 执 行 其 他 命令 行 
时 ， 需 要 把 -g 参 数 也 市 上 ， 否 则 可 能 出 现 配 置 项 不 匹配 的 情形 。 例 
如 ， 如 果 要 停止 Nginx 服 务 ， 那 么 需要 执行 下 面 代码 : 


/usr/local/nginx/sbin/nginx -g "pid /var/nginx/test.pid;" -S stop 


如 果 不 带 上 -g"pid/var/nginx/test.pid;"， 那 么 找 不 到 pid 文 件 ， 也 会 
出 现 无 法 停止 服务 的 情况 。 


(5) 测试 配置 信息 是 否 有 错误 


在 不 启动 Nginx 的 情况 下 ， 使 用 -t 参 数 仅 测试 配置 文件 是 否 有 错 
误 例如 : 


/usr/local/nginx/sbin/nginx -t 


执行 结 采 中 显示 配置 是 否 正确 。 
(6) 在 测试 配置 阶段 不 输出 信息 


测试 配置 选项 时 ， 使 用 -gq 参 数 可 以 不 把 error 级 别 以 下 的 信息 输出 
到 屏 人 莫 。 例 如 : 


/usr/local/nginx/sbin/nginx -t -q 


(7) 显示 版 本 信息 


使 用 -v 参 数 显示 Nginx 的 版 本 信息 。 例 如 : 


/usr/local/nginx/sbin/nginx -v 


(8) 显示 编译 阶段 的 参数 


使 用 -V 参 数 除 了 可 以 显示 Nginx 的 版 本 信息 外 ， 还 可 以 显示 配置 
编译 阶段 的 信息 ， 如 GCC 编 译 锅 的 版 本 、 操 作 系 统 的 版 本 、 执 行 
configure 时 的 参数 等 。 例 如 ; 


/usr/local/nginx/sbin/nginx -V 


(9) 快速 地 停止 服务 


使 用 -s stop 可 以 强制 停止 Nginx 服 务 。-s 参 数 其 实 是 告诉 Nginx 程 序 
癌 正 在 运行 的 Nginx 服 务 发 送信 号 量 ，Nginx 程 序 通 过 nginx.pid 文 件 中 
得 到 master 进 程 的 进程 ID， 再 同 运 行 中 的 master 进 程 发 送 TERM 信 号 来 
快速 地 关闭 Nginx 服 务 。 例 如 : 


/usr/local/nginx/sbin/nginx -s stop 


实际 上 ， 如 果 通 过 kill 命 令 直 接 master 进 程 发 送 TERM 或 者 
INT 人 信号， 效果 是 一 样 的 。 例 如 ， 先 通过 ps 命令 来 查看 nginx master 的 
进程 ID: 


:ahf5wapiool:root > ps -ef | grep nginx 
root 10800 1 0 02:27 ? 00:00:00 nginx: master process ./nginx 
root 10801 10800 0 02:27 ? 00:00:00 nginx: worker process 


接 下 来 直接 通过 kill 命 令 来 发 送信 号 : 


kill -s SIGTERM 10800 


或 者 : 


kill -s SIGINT 10800 


上 述 两 条 命令 的 效果 与 执行 /usr/local/nginx/sbin/nginx-s stop 是 完全 
一 样 的 。 


(10) “优雅 ”地 停止 服务 


如 果 布 望 Nginx 服 务 可 以 正常 地 处 理 完 当 前 所 有 请 求 再 停止 服务 ， 
那么 可 以 使 用 -s quit 参 数 来 停止 服务 。 例 如 : 


/usr/local/nginx/sbin/nginx -s quit 


该 命令 与 快速 分 止 Nginx 服 务 是 有 区 别 的 。 当 快速 停止 服务 时 ， 
worker 进 程 与 master 进 程 在 收 到 信和 号 后 会 立刻 跳出 循环 ， 退 出 进程 。 
而 “优雅 ?地 俘 止 服务 时 ， 首 先 会 天 闭 监 听 端 口 ， 俘 止 接收 新 的 连接 ， 
然后 把 当前 正在 处 理 的 连接 全 部 处 理 完 ， 最 后 再 退出 进程 。 


与 快速 停止 服务 相似 ， 可 以 直接 发 送 QUIT 信 和 号 给 master 进 程 来 停 
止 服务 ， 其 效果 与 执行 -s quit 命 令 是 一 样 的 。 例 如 : 


kill -s SIGQUIT <nginx master pid> 


如 果 希 望 “ 优 雅 * 地 停止 某 个 worker 进 程 ， 那 么 可 以 通过 向 该 进程 
发 送 WINCH 信 号 来 停止 服务 。 例 如 : 


kill -s SIGWINCH <nginx worker pid> 


(11) 使 运行 中 的 Nginx 重 读 配置 项 并 生效 


使 用 -s reload 参 数 可 以 使 运行 中 的 Nginx 服 务 重新 加 载 nginx.conf 文 


/usr/local/nginx/sbin/nginx -s reload 


事实 上 ，Nginx 会 完 检查 新 的 配置 项 是 否 有 误 ， 如 果 全 部 正确 束 
以 “优雅 ”的 方式 关闭， 再 重新 启动 Nginx 来 实现 这 个 目的 。 类 似 的 ，- 
征 发 送信 号 ， 仍 然 可 以 用 kill 命 令 发 送 HUP 信 和 号 来 达到 相同 的 效果 。 


kill -s SIGHUP <nginx master pid> 


(12) 日 志文 件 回 滚 


使 用 -s reopen 参 数 可 以 重新 打开 日 志文 件 ， 这 样 可 以 先 把 当前 日 
志文 件 改名 或 转移 到 其 他 目录 中 进行 备份 ， 再 重新 打开 时 就 会 生成 新 
的 日 志文 件 。 这 个 功能 使 得 日 志文 件 不 至 于 过 大 。 例 如 : 


/usr/local/nginx/sbin/nginx -s reopen 
当然 ， 这 与 使 用 ki 命令 发 送 USR1 信 和 号 效果 相同 。 
kill -s SIGUSR1 <nginx master pid> 
(13) 平滑 升级 Nginx 


当 Nginx 服 务 升 级 到 新 的 版 本 时 ， 必 须要 将 旧 的 二 进 制 文件 Nginx 
蔡 换 挥 ， 通 常情 况 下 这 是 需要 重启 服务 的 ， 但 Nginx 文 持 不 重 局 服务 来 
完成 新 版 本 的 平 请 升级 。 


升级 时 包括 以 下 步 又 : 


1) 通知 正在 运行 的 旧版 本 Nginx 准 备 升级 。 通 过 向 master 进 程 发 
送 USR2 信 号 可 达到 目的 。 例 如 : 


kill -s SIGUSR2 <nginx master pid> 


这 时 ， 运 行 中 的 Nginx 会 将 pid 文 件 重 命名 ， 如 


将 /usr/local/nginx/logs/nginx.pid 重 命名 


为 /usr/local/nginx/logs/nginx.pid.oldbin， 这 样 新 的 Nginx 才 有 可 能 启动 
成 功 。 


2) 启动 新 版 本 的 Nginx， 可 以 使 用 以 上 介绍 过 的 任意 一 种 启动 方 
法 。 这 时 通过 ps 命令 可 以 发 现 新 旧版 本 的 Nginx 在 同时 运行 。 


3) 通过 Kill 命令 向 旧版 本 的 master 进 程 发 送 SIGQUIT 信 和 号， 以 “ 优 
雅 ” 的 方式 关闭 旧版 本 的 Nginx。 ee 污 运行 
此 时 平滑 升级 完毕 。 


(14) 显示 命令 行 帮助 


使 用 -bh 或者-? 参 数 会 显示 文 持 的 所 有 命令 行 参数 。 


17 吉首 


本 章 介绍 了 Nginx 的 特点 以 及 在 什么 场景 下 需要 使 用 Nginx， 同 时 

介绍 了 如 何 获 取 Nginx 以 及 如 何 配 置 、 编 译 、 安 狼 运 行 Nginx。 本草 还 

深入 介绍 了 最 为 复杂 的 configure 过 程 ， 这 部 分 内 容 征 学 习 本 书 第 二 部 
分 和 第 三 部 分 的 基础 。 


第 2 草 Nginx 的 配置 


Nginx 拥 有 大 量 官方 发 布 的 模块 和 第 三 方 模块 ， 这 些 已 有 的 模块 可 
以 帮助 我 们 实现 Web 服 务 郁 上 很 多 的 功能 。 使 用 这 些 模块 时 ， 仅 仅 需 
要 增加 、 修 改 一 些 配 置 项 即 可 。 因 此 ， 本 章 的 目的 是 熟悉 Nginx 的 配置 
文件 ， 包 括 配 置 文件 的 语法 格式 、 运 行 所 有 Nginx 服 务必 须 具 备 的 基础 
配置 以 及 使 用 HTTP 核 心 模块 配置 静 信 Web 服务 需 的 方法 ， 最 后 还 会 介 
绍 反 向 代理 服务 器 。 


通过 本 章 的 学 习 ， 读 者 可 以 ， 熟 练 地 配置 一 个 静态 Web 服 务 右 ; 
对 影响 Web 服 务 硕 性 能 的 各 个 配置 项 有 深入 的 理解 ， 对 配置 语法 有 全 
面 的 了 解 。 通 过 互联 网 或 其 他 途径 得 到 任意 模块 的 配置 说 明 ， 然 后 可 
通过 修改 nginx.conf 文 件 来 使 用 这 些 模块 的 功能 。 


2.1 运行 中 的 Nginx 进 程 间 的 关系 


在 正式 提供 服务 的 产品 环境 下， 部 署 Nginx 时 都 是 使 用 一 个 master 
进程 来 管理 多 个 worker 进 程 ， 一 般 情 况 下 ，worker 进 程 的 数量 与 服务 大 
上 的 CPU 核 心 数 相等 。 每 一 个 worker 进 程 都 是 繁忙 的 ， 它 们 在 真正 地 提 
供 互联 网 服务 ，master 进 程 则 很 “ 清 | 内 ”?”， 只 负责 监控 管理 worker 进 程 。 
worker 进 程 之 间 通 过 共享 内 存 、 原 子 操作 等 一 些 进 程 间 通 信 机 制 来 实现 
负载 均衡 等 功能 (第 9 章 将 会 介绍 负载 均衡 机 制 ， 第 14 章 将 会 介绍 负载 
均衡 锁 的 实现 ) 。 


部 署 后 Nginx 进 程 则 的 天 系 如 图 2-1 所 示 。 


Nginx 是 支持 单 进 程 (master 进 程 ， 提 供 服务 的 ， 那 么 为 什么 产品 
环境 下 要 按照 master-worker 方 式 配 置 同时 启动 多 个 进程 呢 ? 这样 做 的 好 
处 主要 有 以 下 两 点 : 


:由 于 master 进 程 不 会 对 用 户 请 求 提 供 服 务 ， 只 用 于 管理 真正 提供 
服务 的 worker 进 程 ， 所 以 master 进 程 可 以 是 唯一 的 ， 它 仅 专 注 于 目 己 的 
纯 管理 工作 ， 为 管理 员 提 供 命 令 行 服务 ， 包 括 诸如 启动 服务 、 停 止 服 
务 、 重 载 配置 文件 、 平 滑 升 级 程序 等 。master 进 程 需要 拥有 较 大 的 权 
限 ， 例 如 ， 通 常会 利用 root 用 户 局 动 master 进 程 。worker 进 程 的 权限 要 
小 于 或 等 于 master 进 程 ， 这 样 master 进 程 才 可 以 完全 地 管理 worker 进 


程 。 当 任意 一 个 worker 进 程 出 现 错误 从 而 导致 coredump 时 ，master 进 程 
会 立刻 启动 新 的 workerj 进 程 继续 服务 。 


:多 个 worker 进 程 处 理 互联 网 请 求 不 但 可 以 提高 服务 的 健壮 性 (一 
个 worker 进 程 出 错 后 ， 其 他 worker 进 程 仍 然 可 以 正常 提供 服务 ， 最 重 
要 的 是 ， 这 样 可 以 充分 利用 现在 常见 的 SMP 多 核 架 构 ， 从 而 实现 微观 
上 真正 的 多 核 并 发 处 理 。 因 此 ， 用 一 个 进程 master 进 程 ) 来 处 理 互 联 
网 请 求 肯 定 是 不 合适 的 。 男 外 ， 为 什么 要 把 worker 进 程 数 量 设置 得 与 
CPU 核心 数量 一 致 呢 ? 这 正 是 Nginx 与 Apache 服 务 器 的 不 同 之 处 。 在 
Apache 上 每 个 进程 在 一 个 时 刻 只 处 理 一 个 请 求 ， 因 此 ， 如 果 和 希望 Web 服 
务 硬 拥有 并 发 处 理 的 请 求 数 更 多 ， 束 要 把 Apache 的 进程 或 线程 数 设置 
得 更 多 ， 通 第 会 达到 一 台 服 务 絮 拥有 几 百 个 工作 进程 ， 这样 大 量 的 进 
程 间 切 换 将 市 来 无 请 的 系统 资源 消耗 。 而 Nginx 则 不 然 ， 一 个 worker 进 
程 可 以 同时 处 理 的 请 求 数 只 受 限 于 内 存 大 小 ， 而 且 在 染 构 设计 上 上， 不 
同 的 worker 进 程 之 间 处 理 并 发 请 求 时 几乎 没有 同步 锁 的 限制 ，worker 进 
程 通常 不 会 进入 睡眠 状态 ， 因 此 ， 当 Nginx 上 的 进程 数 与 CPU 核 心 数 相 
等 时 (最 好 每 一 个 worker 进 程 都 绑 定 特定 的 CPU 核 心 ) ， 进 程 间 切换 的 


代价 是 最 小 的 。 
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图 2-1 部 署 后 Nginx 进 程 间 的 关系 


举例 来 说 ， 如 果 产 品 中 的 服务 器 CPU 核心 数 为 8， 那 么 就 需要 配置 
8 个 worker 进 程 〈 见 图 2-2) 。 


PID USER TIME+ COMMAND 
Dc ~ 十 r Y 83: 了 .15 nainx: 与 己 十 已 + 


We 芝 : 


图 2-2 ”worker 进 程 的 数量 尽量 与 CPU 核心 数 相等 


如 果 对 路 径 部 分 都 使 用 黑 认 配置 ， 那 么 Nginx 运 行 目 录 
为 /usr/local/nginx， 其 目录 结构 如 下 。 


|---sbin 

| |---nginx 

|---conf 

| |---koi-win 

| |---koi-utf 

| |---win-utf 

| |---mime.types 

| |---mime.types.default 

| |---fastcgi_params 

| |---fastcgi_params.default 
| |---fastcgi,conf 

| |---fastcgi,.conf.default 
| |---uwsgi_params 

| |---uwsgi_params.default 
| |---scgi_params 

| |---scgi_params.default 
| |---nginx.conf 

| |---nginx.conf.default 
|---logs 

| |---error.1og 

| |---access.1og 

| |---nginx.pid 

|---html 


|---50x.html 


|---index.html 
---Client_body_temp 


---fastcgi temp 
---Uwsgi_temp 


| 

| 

| 
|---proxy_temp 
| 

| 

|---scgi_temp 


2.2 Nginx 配 置 的 通用 语法 


Nginx 的 配置 文件 其 实 是 一 个 普通 的 文本 文件 。 下 面 来 看 一 个 简单 
的 例子 。 


User nobody; 
worker_processes 8; 
error_log /var/log/nginx/error.1log error,; 
#pid logs/nginx.pid; 
events { 
use epoll; 
worker_connections 50000; 
} 
http { 
include mime.types; 
default_type application/octet-stream; 
log format main '$remote addr [$time local] "$request" ' 
'$status $bytes_sent "$http_referer" ' 
'"$http_user_agent" "$http_x_forwarded_for"'; 
access log logs/access.log main buffer=32k; 


在 这 段 简短 的 配置 代码 中 ， 每 一 行 配置 项 的 语法 格式 都 将 在 2.2.2 
节 介 绍 ， 出 现 的 events 和 http 块 配置 项 将 在 2.2.1 廊 介绍 ， 以 # 符 号 开 尖 
的 注释 将 在 2.2.3 广 介绍 ， 类 似 “buffer=32k” 这 样 的 配置 项 的 单位 将 在 


2.2.4 广 介绍 。 


2.2.1 块 配 置 项 


块 配置 项 由 一 个 块 配置 项 名 和 一 对 大 括号 组 成 。 具 体 示 例如 下 : 


events {... 


} 
http { 
upstream backend { 

server 127.0.0.1:8080,; 


gzip on; 
server { 


location /webstatic f{ 
gzip off; 


上 面 代 码 段 中 的 events、http、server、location、upstream 等 都 是 块 
配置 项 ， 块 配置 项 之 后 是 否 如 “location/webstatic{.…}" 那 样 在 后 面 加 上 
参数 ， 取 决 于 解析 这 个 块 配置 项 的 模块 ， 不 能 一 概 而 论 ， 但 块 配置 项 
一 定 会 用 大 括号 把 一 系列 所 属 的 配置 项 全 包含 进来 ， 表 示 大 括号 内 的 
配置 项 同时 生效 。 所 有 的 事件 类 配置 都 要 在 events 块 中 ，http 、server 
等 配置 也 遵循 这 个 规定 。 


块 配 置 项 可 以 租 套 。 内 层 块 直接 继承 外 层 块 ， 例 如 ， 上 例 中 ， 
server 块 里 的 任意 配置 都 是 基于 http 块 里 的 已 有 配置 的 。 当 内 外 层 块 中 
的 配置 发 生 冲 突 时 ， 究 竟 是 以 内 层 块 还 是 外 层 块 的 配置 为 准 ， 取 决 于 
解析 这 个 配置 项 的 模块 ， 第 4 章 将 会 介绍 http 块 内 配置 项 冲突 的 处 理 方 
法 。 例 如 ， 上 例 在 http 模 块 中 已 经 打开 了 “gzip on;j”， 但 其 下 的 
location/webstatic 又 把 gzip 关 闭 了 : gzip off;， 最 终 ， 在 /webstatic 的 处 理 
模块 中 ，gzip 模 块 是 按照 gzip off 来 处 理 请 求 的 。 


2.2.2 ”配置 项 的 语法 格式 


从 上 文 的 示例 可 以 看 出 ， 最 基本 的 配置 项 语法 格式 如 下 : 


配置 项 名 
配置 项 值 


1 配置 项 值 


从 we 


F 面 解释 一 下 配置 项 的 构成 部 分 。 


首先 ， 在 行 首 的 是 配置 项 名 ， 这 些 配置 项 名 必须 是 Nginx 的 某 一 个 
模块 想 要 处 理 的 ， 否 则 Nginx 会 认为 配置 文件 出 现 了 非法 的 配置 项 名 。 
配置 项 名 输入 结束 后 ， 将 以 空格 作为 分 隅 符 。 


其 次 十 配置 项 值 ， 它 可 以 古 数 子 或 字符 串 (当然 也 包括 正则 表达 
式 ) 。 针 对 一 个 配置 项 ， 既 可 以 只 有 一 个 值 ， 也 可 以 包含 多 个 值 ， 配 
置 项 值 之 间 仍然 由 空格 符 来 分 隔 。 当 然 ， 一 个 配置 项 对 应 的 值 客 竞 有 
多 少 个 ， 取 决 于 解析 这 个 配置 项 的 模块 。 我 们 必须 根据 某 个 Nginx 模 块 
对 一 个 配置 项 的 约定 来 更 改 配置 项 ， 第 4 章 将 会 介绍 模块 是 如 何 约 定 一 
个 配置 项 的 格式 。 


最 后 ， 每 行 配置 的 结尾 需要 加 上 分 号 。 


@@ 注音。 如果 配 置 项 值 中 包括 语法 符号 ， 比 如 空格 符 ， 那 么 需 
要 使 用 单 引号 或 双 引号 括 住 配置 项 值 ， 否 则 Nginx 会 报 语法 错误 。 例 
如 ， 


log format main '$remote addr - $remote user [$time local] "$request" '; 


2.2.3 配置 项 的 注释 


如 果 有 一 个 配置 项 暂时 需要 注释 掉 ， 那 么 可 以 加 "注释 掉 这 一 行 
配置 。 例 如 ， 


#pid logs/nginx.pid; 


2.2.4 配置 项 的 单位 

大 部 分 模块 遵循 一 些 通用 的 规定 ， 如 指定 空间 大 小 时 不 用 每 次 都 
定义 到 字 节 、 指 定时 间 时 不 用 精确 到 毫秒 。 

当 指 定 空间 大 小 时 ， 可 以 使 用 的 单位 包括 : 

区 或 者 k 千 字 节 (KiloByte，KB) 。 


.M 或 者 m 兆 字 季 (MegaByte, MB) 。 


例如 : 


gzip_buffers 8k; 
client_max_body_size 64M; 


当 指 定时 间 时 ， 可 以 使 用 的 单位 包括 : 


:ms (上 毫秒) ，s ( 秒 ) ，m (分 钟 ) ，h (小 时 ) ，d (天 ) ，w 
( 周 ， 包含 7 天 ) ，M (月 ， 包 含 30 天 ) ，y (年 ,包含 365 天 ) 。 


例如 : 
expires 10y; 
proxy_read_ timeout 600 
client_body_timeout 2m; 


人 @@ 注意 ”配置 项 后 的 值 完 竟 是 否 可 以 使 用 这 些 单位 ， 取 决 于 解 
析 该 配置 项 的 模块 。 如 果 这 个 模块 使 用 了 Nginx 框 架 提 供 的 相应 解析 配 
置 项 方法 ， 那 么 配置 项 值 才 可 以 携带 单位 。 第 4 章 中 详细 描述 了 Nginx 
框架 提供 的 14 种 预 设 解析 方法 ， 其 中 一 些 方法 将 可 以 解析 以 上 列 出 的 
单位 。 


2.2.5 在 配置 中 使 用 变量 


有 些 模块 允许 在 配置 项 中 使 用 变量 ， 如 在 日 志 记 录 部 分 ， 具 体 示 
例如 下 。 


log format main '$remote addr - $remote user [$time local] "$request" ' 
'$status $bytes_sent "$http_referer" ' 
'"$http_user_agent" "$http_x_forwarded_for"'; 


其 中 ，remote_addr 是 一 个 变量 ， 使 用 它 的 时 候 前 面 要 加 上 $ 符 
° 需要 注意 的 是 ， 这 种 变量 只 有 少数 模块 支持 ， 并 不 是 通用 的 。 


< 了 


许多 模块 在 解析 请 求 时 都 会 提供 多 个 变量 《如 本 章 后 面 提 到 的 
http core module、http proxy module、http upstream module 等 ) ， 以 使 
其 他 模块 的 配置 可 以 即时 使 用 。 我 们 在 学 习 某 个 模块 提供 的 配置 说 明 


时 可 以 关注 它 是 否 提供 变量 。 


@ 是 示 “在 执行 configure 命 令 时 ， 我 们 已 经 把 许多 模块 编译 进 
Nginx 中 ， 但 是 否 启用 这 些 模块 ， 一 般 取 决 于 配置 文件 中 相应 的 配置 
项 。 换 句 话说 ， 每 个 Nginx 模 块 都 有 自己 感 兴趣 的 配置 项 ， 大 部 分 模块 
都 必须 在 nginx.conf 中 读 取 某 个 配置 项 后 才 会 在 运行 时 启用 。 例 如 ， 只 
有 当 配置 http{.} 这 个 配置 项 时 ，ngx_http_module 模 块 才 会 在 Nginx 中 
启用 ， 其 他 依赖 ngx_http_module 的 模块 也 才能 正常 使 用 。 


2.3 Nginx 服 务 的 基本 配置 


Nginx 在 运行 时 ， 至 少 必 须 加 载 几 个 核心 模块 和 一 个 事件 类 模块 。 
这 些 模块 运行 时 所 文 持 的 配置 项 称 为 基本 配置 一 所 有 其 他 模块 执行 
时 都 依赖 的 配置 项 。 
下 面 详 述 基本 配置 项 的 用 法 。 由 于 配置 项 较 多 ， 所 以 把 它们 按照 
用 户 使 用 时 的 预期 功能 分 成 了 以 下 4 类 : 
:用 于 调试 、 定 位 问题 的 配置 项 。 
正常 运行 的 必 备 配置 项 。 
.优化 性 能 的 配置 项 。 
事件 类 配置 项 (有 些 事件 类 配置 项 归纳 到 优化 性 能 类 ， 这 是 因为 
它们 虽然 也 属于 events{} 块 ， 但 作用 是 优化 性 能 ) 。 
有 这 么 一 些 配置 项 ， 即 使 没有 显 式 地 进行 配置 ， 它 们 也 会 有 默认 
的 值 ， 如 daemon， 即 使 在 nginx.conf 中 没有 对 它 进 行 配置 ， 也 相当 于 打 
开 了 这 个 功能 ， 这 点 需要 注意 。 对 于 这 样 的 配置 项 ， 作 者 会 在 下 面相 
应 的 配置 项 描述 上 加 入 一 行 “ 默 认 : ?来 进行 说 明 。 


2.3.1 用 于 调 话 进程 和 定位 问题 的 配置 项 


先 来 看 一 下 用 于 调试 进程 、 定 位 问题 的 配置 项 ， 如 下 所 示 。 
(1) 是 否 以 守护 进程 方式 运行 Nginx 

语法 : daemon onloff; 

默认 : daemon on; 


守护 进程 (daemon) 是 脱离 终端 并 且 在 后 全 运行 的 进程 。 它 脱离 
终端 是 为 了 避免 进程 执行 过 程 中 的 信息 在 任何 终端 上 显示 ， 这 样 一 
来 ， 进 程 也 不 会 被 任何 终端 所 产生 的 信息 所 打上 晰 。Nginx 受 无 疑问 是 一 
个 需要 以 守护 进程 方式 运行 的 服务 ， 因 此 ， 稚 认 都 旦 以 这 种 方式 运行 
胸 。 


不 过 Nginx 还 是 提供 了 关闭 守护 进程 的 模式 ， 之 所 以 提供 这 种 模 
式 ， 是 为 了 方便 跟 踩 调试 Nginx， 毕 竟 用 gdb 调 试 进程 时 最 烦琐 的 殉 是 
如 何 继续 跟 进 fork 出 的 子 进 程 了 。 这 在 第 三 部 分 研究 Nginx 架 构 时 很 有 
用 。 


(2) 是 否 以 master/worker 方 式 工 作 


语法 : master_process on|off; 


默认 : master_process on, 


可 以 看 到 ， 在 如 图 2-1 所 示 的 产品 环境 中 ， 是 以 一 个 master 进 程 管 
理 多 个 worker 进 程 的 方式 运行 的 ， 几 乎 所 有 的 产品 环境 下 ，Nginx 都 以 
这 种 方式 工作 。 


与 daemon 配 置 相同 ， 提 供 master_process 配 置 也 是 为 了 方便 跟踪 调 
试 Nginx。 如 果 用 off 关 闭 了 master_process 方 式 ， 就 不 会 fork 出 worker 子 
进程 来 处 理 请 求 ， 而 是 用 master 进 程 日 身 来 处 理 请 求 。 


(3) error 日 志 的 设置 
语法 : ”error_log/path/file level; 


默认 :，error_log logs/error.log error; 


error 日 志 是 定位 Nginx 问 题 的 最 佳 工具 ， 我 们 可 以 根据 目 己 的 需求 


妥善 设置 error 日 志 的 路 人 径 和 级 别 。 


/path/file 参 数 可 以 是 一 个 具体 的 文件 ， 例 如 ， 上 默认 情况 下 是 
logs/error.log 文 件 ， 最 好 将 它 放 到 一 个 人 磁盘 空间 足够 大 的 位 
置 ，/path/fle 也 可 以 是 /dev/null， 这 样 束 不 会 输出 任何 日 志 了 ， 这 也 是 
关闭 error 日 志 的 唯一 手段 ，/path/file 也 可 以 是 stderr， 这 样 日 志 会 输出 
到 标准 错误 文件 中 。 


leve] 是 日 志 的 输出 级 别 ， 取 值 范 围 是 debug、info、notice、warn、 
error、 crit、alert、emerg， 从 左 至 右 级 别 依次 增 大 。 当 设 定 为 一 个 级 别 
时 ， 大 于 或 等 于 该 级 别 的 日 志 都 会 被 输出 到 /path/file 文 件 中 ， 小 于 该 
级 别 的 日 志 则 不 会 输出 。 例 如 ， 当 设 定 为 error 级 别 时 ，error 、 crit、 
alert、emerg 级 别 的 日 志 都 会 输出 。 


如 果 设 定 的 日 志 级 别 是 debug， 则 会 输出 所 有 的 日 志 ， 这 样 数据 量 
会 很 大 ， 需 要 预先 确 保 /path/file 所 在 人 磁盘 有 尼 够 的 磁 副 空间 。 


人 @@ 注意 如 果 日 志 级 别 设 定 到 debug， 必 须 在 configure 时 加 入 -- 
with-debug 配 置 项 。 


(4) 是 否 处 理 几 个 特殊 的 调试 点 
语法 : debug_points[stoplabort] 


这 个 配置 项 也 是 用 来 帮助 用 户 跟踪 调试 Nginx 的 。 它 接受 两 个 参 
数 : stop 和 abort。Nginx 在 一 些 关 键 的 错误 逻辑 中 (Nginx 1.0.14 版 本 中 
有 8 处 ) 设置 了 调试 点 。 如 果 设 置 了 debug_points 为 stop， 那 么 Nginx 的 
代码 执行 到 这 些 调试 点 时 就 会 发 出 SIGSTOP 信 和 号 以 用 于 调试 。 如 果 
debug_points 设 置 为 abort， 则 会 产生 一 个 coredump 文 件 ， 可 以 使 用 gdb 
来 查看 Nginx 当 时 的 各 种 信息 。 


通常 不 会 使 用 这 个 配置 项 。 


(5) 仅 对 指定 的 客户 端 输出 debug 级 别 的 日 志 


语法 : debug_connection[IP|CIDR] 


这 个 配置 项 实际 上 属于 事件 类 配置 ， 因 此 ， 它 必须 放 在 eventst{...} 
中 才 有 效 。 它 的 值 可 以 是 IP 地 址 或 CIDR 地 址 ， 例 如 : 


events { 
debug_connection 10.224.66.14; 
debug_connection 10.224.57.0/24; 
} 


这 样 ， 仅 仅 来 目 以 上 IP 地 址 的 请 求 才 会 输出 debug 级 别 的 日 志 ， 其 
他 请 求 仍然 沿用 error_log 中 配置 的 日 志 级 别 。 


上 面 这 个 配置 对 修复 Bug 很 有 用 ， 特 别 是 定位 高 并 发 请 求 下 才 会 
发 生 的 问题 。 


er 注意 “使 用 debug_connection 前 ， 需 确保 在 执行 configure 时 已 
经 加 入 了 --with-debug 参 数 ， 人 否则 不 会 生效。 


(6) 限制 coredump 核 心 转 储 文件 的 大 小 
语法 :， worker_rlimit _ core size: 


在 Linux 系 统 中 ， 当 进程 发 生 错误 或 收 到 信和 号 而 终止 时 ， 系 统 会 将 
进程 执行 时 的 内 存 内 容 (核心 映像 ， 写 入 一 个 文件 (core 文 件 ) ， 以 


作为 调试 之 用 ， 这 就 是 所 谓 的 核心 转 储 (core dumps) 。 当 Nginx 进 程 
出 现 一 些 非法 操作 (如 内 存 越界 ) 导致 进程 直接 被 操作 系统 强制 结 
时 ， 会 生成 核心 转 储 core 文 件 ， 可 以 从 core 文 件 获取 当时 的 堆栈 、 寄 存 
妖 等 信息 ， 从 而 帮助 我 们 定位 问题 。 但 这 种 core 文 件 中 的 许多 信息 不 
定 是 用 户 需 要 的 ， 如 有 果 不 加 以 限制 ， 那 么 可 能 一 个 core 文 件 会 达到 
几 GB， 这 样 随便 coredumps 几 次 束 会 把 磁盘 占 满 ， 引 发 疡 重 问题 。 通 
过 Worker_rlimit_core 配 置 可 以 限制 core 文 件 的 大 小 ， 从 而 有 效 帮 助 用 户 


定位 问题 。 


(7) 指定 coredump 文 件 生成 目录 
语法 : working_directory path; 


worker 进 程 的 工作 目录 。 这 个 配置 项 的 唯一 用 途 束 是 设置 
coredump 文 件 所 放置 的 目录 ， 协 助 定位 问题 。 因 此 ， 需 确保 worker 进 
程 有 权限 同 working_directory 指 定 的 日 录 中 写 入 文件 。 


2.3.2 ”正常 运行 的 配置 项 


下 面 古 正常 运行 的 配置 项 的 相关 介绍 。 
(1) 定义 环境 变量 


语法 : env VARIVAR=VALUE 


这 个 配置 项 可 以 让 用 户 直接 设置 操作 系统 上 的 环境 变量 。 例 如 : 


env TESTPATH=/tmp/; 


(2) 艇 入 其 他 配置 文件 
语法 : include/pathyfile; 


include 配 置 项 可 以 将 其 他 配置 文件 区 入 到 当前 的 nginx.conf 文 件 
中 ， 它 的 参数 既 可 以 是 绝对 路 径 ， 也 可 以 是 相对 路 径 (相对 于 Nginx 的 
配置 目录 ， 即 nginx.conf 所 在 的 目录 ) ， 例 如 : 


include mime.types; 
include vhost/*.conf; 


可 以 看 到 ， 参 数 的 值 可 以 是 一 个 明确 的 文件 名 ， 也 可 以 古 舍 有 通 
配 符 * 的 文件 名 ， 同 时 可 以 一 次 甬 入 多 个 配置 文件 。 


(3) pid 文 件 的 路 径 
语法 : ”pid path/file; 
趴 认 :， pid logs/nginx.pid; 


保存 master 进 程 ID 的 pid 文 件 存放 路 径 。 默 认 与 configure 执 行 时 的 
参数 “--pid-path” 所 指定 的 路 径 是 相同 鸭 ， 也 可 以 随时 修改 ， 但 应 确保 


Nginx 有 权 在 相应 的 目标 中 创建 pid 文 件 ， 该 文件 直接 影响 Nginx 古 否 可 


一 


以 运行 。 
(4) Nginx worker 进 程 运行 的 用 户 及 用 户 组 
语法 : ”user username[groupname]; 
默认 :， user nobody nobody:; 


user 用 于 设置 master 进 程 启动 后 ，fork 出 的 worker 进 程 运行 在 哪个 
用 户 和 用 户 组 下 。 当 按照 “user usemame:” 设 置 时 ， 用 户 组 名 与 用 户 名 
相同 。 


若 用 户 在 configure 命 令 执行 时 使 用 了 参数 --user=username 和 -- 
group=groupname， 此 时 nginx.conf 将 使 用 参数 中 指定 的 用 户 和 用 户 
组 。 


(5) 指定 Nginx workerj 进 程 可 以 打开 的 最 大 句柄 描述 符 个 数 
语法 : worker_rlimit_nofile limit; 
设置 一 个 worker 进 程 可 以 打开 的 最 大 文件 句柄 数 。 

(6) 限制 信号 队列 


语法 : worker_rlimit_sigpending limit; 


设置 每 个 用 户 发 往 Nginx 的 信号 队列 的 大 小 。 也 融 是 说 ， 当 某 个 用 
尸 的 信号 队列 满 了 ， 这 个 用 户 再 发 送 的 信号 量 会 被 丢 控 。 


233 做 化 让 能 办 本 是 需 
下 面 是 优化 性 能 的 配置 项 的 相关 介绍 。 
(1) Nginx worker 进 程 个 数 
语法 : ”worker_processes number; 


默认 :，worker_processes 1; 


在 master/worker 运 行 方式 下 ， 定 义 worker 进 程 的 个 数 。 


worker 进 程 的 数量 会 直接 影响 性 能 。 那 么 ， 用 户 配 置 多 少 个 
worker 进 程 才 好 呢 ? 这 实际 上 与 业务 需求 有 关 。 


每 个 worker 进 程 都 是 单线 程 的 进程 ， 它 们 会 调用 各 个 模块 以 实现 
多 种 多 样 的 功能 。 如 果 这 些 模块 确认 不 会 出 现 阻塞 式 的 调用 ， 那 么 ， 
有 多 少 CPU 内 核 就 应 该 配置 多 少 个 进程 ， 反 之 ， 如 果 有 可 能 出 现 阻塞 
式 调用 ， 那 么 需要 配置 稍 多 一 些 的 worker 进 程 。 


例如 ， 如 果 业 务 方面 会 致使 用 户 请 求 大 量 读 取 本 地 磁盘 上 的 静态 
资源 文件 ， 而 且 服 务 右 上 的 内 存 较 小 ， 以 至 于 大 部 分 的 请 求 访问 静态 


资源 文件 时 都 必须 读 取 磁盘 (磁头 的 寻 址 是 缓慢 的 ) ， 而 不 是 内 存 中 
的 傍 盘 缓存 ， 那 么 傍 一 IO 调用 可 能 会 阻塞 住 workerj 井 程 少 量 时 间 ， 进 
而 导致 服务 整体 性 能 下 降 。 

多 worker 进 程 可 以 充分 利用 多 核 系 统 架构 ， 但 大 worker 进 程 的 数 
量 多 于 CPU 内 核 数 ， 那 么 会 增 大 进程 间 切 换 带 来 的 消耗 (Linux 是 抢占 
式 内 核 ) 。 一 般 情 况 下 ， 用 户 要 配置 与 CPU 内 核 数 相等 的 worker 进 
程 ， 并且 使 用 下 面 的 worker_cpu_affinity 配 置 来 绑 定 CPU 内 核 。 

(2) 绑 定 Nginx worker 进 程 到 指定 的 CPU 内 核 


语法 : worker_cpu_affinity cpumask[cpumask...] 


为 什么 要 绑 定 worker 进 程 到 指定 的 CPU 内 核 呢 ? 假定 每 一 个 
worker 进 程 都 是 非常 繁忙 的 ， 如 果 多 个 worker 进 程 都 在 抢 同一 个 
CPU， 那 么 这 就 会 出 现 同步 问题 。 反 之 ， 如 采 每 一 个 worker 进 程 都 独 
译 一 个 CPU， 就 在 内 核 的 调度 策略 上 实现 了 完全 的 并 发 。 


例如 ， 如 果 有 4 颗 CPU 内 核 ， 束 可 以 进行 如 下 配置 : 


worker_processes 4; 
worker_cpu_affinity 1000 0100 0010 0001; 


@ 注意 “worker_cpu_affinity 配 置 仅 对 Linux 操 作 系统 有 效 。 
Linux 操 作 系 统 使 用 sched_setaffinity() 系 统 调 用 实现 这 个 功能 。 


(3) SSL 硬 件 加 速 
语法 : ssl_engine device; 


如 果 服 务 器 上 有 SSL 人 硬件 加 速 设备 ， 那 么 就 可 以 进行 配置 以 加 快 
SSL 协 议 的 处 理 速度 。 用 户 可 以 使 用 OpenSSL 提 供 的 命令 来 查看 是 否 
有 SSL 硬 件 加 速 设 备 : 


openssl] engine -t 


(4) 系统 调用 gettimeofday 的 执行 频率 
语法 : timer_resolution ti; 


默认 情况 下 ， 每 次 内 核 的 事件 调用 (如 epoll 、select、pol、 
kqueue 等 ) 返回 时 ， 都 会 执行 一 次 gettimeofday， 实 现 用 内 核 的 时 钟 来 
更 新 Nginx 中 的 缓存 时 钟 。 在 早期 的 Linux 内 核 中 ，gettimeofday 的 执行 
代价 不 小 ， 因 为 中 间 有 一 次 内 核 态 到 用 户 态 的 内 存 复制 。 当 需要 降低 
gettimeofday 的 调用 频率 上 时， 可 以 使 用 timer_resolution 配 置 。 例 


如 ，“timer resolution 100ms; ”表示 至 少 每 100ms 才 调用 一 次 


gettimeofday ° 


但 在 目前 的 大 多 数 内 核 中 ， 如 x86-64 体 系 染 构 ，gettimeofday 只 是 
一 次 vsyscall， 仅 仅 对 共享 内 存 页 中 的 数据 做 访问 ， 并 不 是 通常 的 系统 


调用 ， 代 价 并 不 大 ， 一 般 不 必 使 用 这 个 配置 。 而 且 ， 如 采 硕 望 日 志文 
件 中 每 行 打印 的 时 间 更 准确 ， 也 可 以 使 用 它 。 


(5) Nginx worker 进 程 优先 级 设置 
语法 : ”worker_priority nice; 
直 认 : worker_priority 0; 
该 配置 项 用 于 设置 Nginx worker 进 程 的 nice 优 先 级 。 


在 Linux 或 其 他 类 UNIX 操 作 系 统 中 ， 当 许多 进程 都 处 于 可 执行 状 
态 时 ， 将 按照 所 有 进程 的 优先 级 来 决定 本 次 内 核 选 择 哪 一 个 进程 执 
。 进程 所 分 配 的 CPU 时 间 片 大 小 也 与 进程 优先 级 相关 ， 优 和 级 越 
高 ， 进 程 分 配 到 的 时 间 片 也 就 越 大 例如， 在 默认 配置 下 ， 最 小 的 时 
间 片 只 有 5ms， 最 大 的 时 间 片 则 有 800ms) 。 这 样 ， 优 先 级 高 的 进程 会 
占有 更 多 的 系统 资源 。 


—~、\ 
a 


优先 级 由 静态 优 移 级 和 内 核 根 据 进 程 执行 情况 所 做 的 动态 调整 
(目前 只 有 +5 的 调整 ， 共 同 决 定 。nice 值 是 进程 的 静态 优先 级 ， 它 的 
取 值 范围 古 -20~+19，-20 是 最 蜗 优 先 级 ，+19 是 最 低 优先 级 。 因 此 ， 
如 打 用 户 和 硕 望 Nginx 占 有 更 多 的 系统 资源 ， 那 么 可 以 把 nice 值 配置 得 更 
小 一 些 ， 但 不 建议 比 内 核 进程 的 nice 值 (通常 为 -5) 还 要 小 。 


2.3.4 ”事件 类 配置 项 


下 面 是 事件 类 配置 项 的 相关 介绍 。 
(1) 是 否 打开 accept 饥 

语法 : accept_mutex[on|off] 

默认 : accept_mutext on; 


accept_mutex 是 Nginx 的 负载 均衡 锁 ， 本 书 会 在 第 9 草 事 件 处 理 杠 
架 中 详 述 Nginx 是 如 何 实现 负载 均衡 的 。 这 里 ， 读 者 仅 需 要 知道 
accept_mutex 这 把 锁 可 以 让 多 个 worker 进 程 轮流 地 、 序 列 化 地 与 新 的 客 
己 问 建 并 TCP 连 授 。 当 某 一 个 worker 进 程 建立 的 连接 数量 达到 
worker_connections 配 置 的 最 大 连接 数 的 718 时 ， 会 大 大 地 减 小 该 worker 
进程 试图 建立 新 TCP 连 接 的 机 会 ， 以 此 实现 所 有 worker 进 程 之 上 处 理 
的 客户 端 请 求 数 尽量 接近 。 


accept 旬 (默认 是 打开 的 ， 如 果 关 闭 它 ， 那 么 建立 TCP 连 接 的 耗 时 会 
更 短 ， 但 worker 进 程 之 间 的 负载 会 非常 不 均衡 ， 因 此 不 建议 关闭 它 。 


(2) lock 文 件 的 路 径 


语法 : lock_file path/file; 


BA: lock file logs/nginx.lock; 


accept 锁 可 能 需要 这 个 lock 文 件 ， 如 琳 accept 锁 关闭 ，lock_file 配 置 
完全 不 生效 。 如 果 打 开 了 accept 锁 ， 并 且 由 于 编译 程序 、 操 作 系统 杂 
构 等 因素 导致 Nginx 不 文 持原 子 锁 ， 这 时 才 会 用 文件 锁 实现 accept 锁 

14.8.1 节 将 会 介绍 文件 锁 的 用 法 ) ， 这 样 lock_file 指 定 的 lock 文 件 才 


@ 注意 ”在 基于 i386、AMD64、Sparc64、PPC64 体 系 架 构 的 操 
作 系 统 上 ， 若 使 用 GCC、Intel C++、SunPro C++ 编译 喜来 编译 Nginx， 
则 可 以 表 定 这 时 的 Nginx 是 支持 原子 锁 的 ， 因 为 Nginx 会 利用 CPU 的 特 
性 并 用 汇编 语言 来 实现 它 (可 以 参考 14.3 节 x86 染 构 下 原子 操作 的 实 
现 ) 。 这 时 的 lock_file 配 置 是 没有 意义 的 。 


(3) 使 用 accept 锁 后 到 真正 建立 连接 之 间 的 延迟 时 间 
语法 : accept_mutex_delay Nms; 
跃 认 : accept_mutex_delay 500ms; 


在 使 用 accept 锁 后 ， 同 一 时 间 只 有 一 个 worker 进 程 能 够 取 人 到 accept 
锁 。 这 个 accept 锁 不 是 阻塞 锁 ， 如 果 取 不 到 会 立刻 返回 。 如 条 有 一 个 
worker 进 程 试图 取 accept 锁 而 没有 取 到 ， 它 至 少 要 等 
accept_mnutex_delay 定 义 的 时 间 间 隅 后 才能 再 次 试图 取 锁 。 


(4) 批量 建立 新 连接 
语法 : multi_accept[onloff]; 
默认 : multi_accept off; 


当 事 件 模 型 通知 有 新 连接 时 ， 尽 可 能 地 对 本 次 调度 中 客户 病 发 起 
的 所 有 TCP 请 求 都 建立 连接 。 


) 选择 事件 模型 


-一 、 
Ul 


语法 : ”use[kqueuelrtsiglepoll|/dev/poll|select|lpollleventport]; 


默认 : Nginx 会 自动 使 用 最 适合 的 事件 模型 。 


对 于 Linux 控 作 系 统 来 说 ， 可 供 选 择 的 事件 驱动 模型 有 poll、 
select、epoll 三 种 。epoll 当 然 是 性 能 最 高 的 一 种 ， 在 9.6 广 会 解释 epoll 为 
什么 可 以 处 理 大 并 发 连接 。 


(6) 每 个 worker 的 最 大 连接 数 
语法 : worker_connections number:; 


定义 每 个 worker 进 程 可 以 同时 人 处理 的 最 大 连接 数 。 


2.4 用 HTTP 核 心 模 块 配置 一 个 静态 Web 服 务 需 


静态 Web 服 务 器 的 主要 功能 由 ngx_http_core_module 模 块 (HTTP 框 

架 的 主要 成 员 ) 实现 ， 当 然 ， 一 个 完整 的 静态 Web 服 务 器 还 有 许多 功能 
是 由 其 他 的 HTTP 模块 实现 的 。 本 节 主 要 讨论 如 何 配置 一 个 包含 基本 功 

能 的 静态 Web 服 务 器 ， 文 中 会 完整 地 说 明 ngx_http_core_module 模 块 提 
供 的 配置 项 及 变量 的 用 法 ， 但 不 会 过 多 说 明 其 他 HTTP 模 块 的 配置 项 。 
在 阅读 完 本 节 内 容 后 ， 读 者 应 当 可 以 通过 简单 的 查询 相关 模块 (如 
ngx_http_gzip_filter_module、ngx_http_image filter_module 等 ) 的 配置 
项 说 明 ， 方 便 地 在 nginx.conf 配 置 文 件 中 加 入 新 的 配置 项 ， 从 而 实现 更 
多 的 Web 服 务 器 功能 。 


除了 2.3 太 提 到 的 基本 配置 项 外 ， 一 个 典型 的 静态 Web 服 务 器 还 会 
包含 多 个 server 块 和 location 块 ， 例 如 : 


http { 
gzip on; 
upstream { 


server { 
listen localhost:80; 


location /webstatic { 
下 下 .全 


} 
root /opt/webresource; 


} 
location ~* .(jpgljpeglpng|jpelgif)$ { 


} 


server { 


} 


所 有 的 HTTP 配 置 项 都 必须 直属 于 http 块 、server 块 、location 块 、 
upstream 块 或 if 块 等 (HTTP 配 置 项 自然 必须 全 部 在 http{} 块 之 内 ， 这 里 
的 “直属 于 ?是 指 配置 项 直接 所 属 的 大 括号 对 应 的 配置 块 ) ， 同 时 ， 在 
描述 每 个 配置 项 的 功能 时 ， 会 说 明 它 可 以 在 上 述 的 哪个 块 中 存在 ， 因 
为 有 些 配置 项 可 以 任意 地 出 现在 某 一 个 块 中 ， 而 有 些 配置 项 只 能 出 现 
在 特定 的 块 中 ， 在 第 4 章 介 绍 目 定义 配置 项 的 读 取 时 ， 相 信 读 者 就 会 体 
会 到 这 种 设计 思路 。 


Nginx 为 配置 一 个 完整 的 静态 Web 服 务 紫 提供 了 非 第 多 的 功能 ， 
面 会 把 这 些 配 置 项 分 为 以 下 8 类 进行 详 述 ， 虚拟 主机 与 请 求 的 分 发 、 文 
件 路 径 的 定义 、 内 存 及 人 磁 副 资源 的 分 配 、 网 络 连接 的 设置 、MIME 类 型 
的 设置 、 对 客户 端 请 求 的 限制 、 文 件 操作 的 优化 、 对 客户 端 请 求 的 特 
殊 处 理 。 这 种 划分 只 是 为 了 帮助 大 家 从 功能 上 理解 这 些 配置 项 。 


在 这 之 后 会 列 出 ngx_http_core_module 模 块 提供 的 变量 ， 以 及 人 简单 
说 明 它 们 的 意义 。 


2.4.1 ”虚拟 主机 与 请 求 的 分 发 


由 于 IP 地 址 的 数量 有 限 ， 因 此 经 常 存在 多 个 主机 域名 对 应 着 同一 
个 IP 地 址 的 情况 ， 这 时 在 nginx.conf 中 就 可 以 按照 server_name (对 应 用 
户 请 求 中 的 主机 域名 ) 并 通过 server 块 来 定义 虚拟 主机 ， 每 个 server 块 就 
是 一 个 虚拟 主机 ， 它 只 处 理 与 之 相对 应 的 主机 域名 请 求 。 这 样 ， 一 台 
服务 右上 的 Nginx 束 能 以 不 同 的 方式 处 理 访问 不 同 主机 域名 的 HTTP 请 
求 了 。 


(1) 监听 端口 


语法 : listen address:port[default(deprecated in 0.8.21)|default_server| 
[backlog=numlrcvbuf=sizelsndbuf=sizelaccept_filter=filter|deferred|bind|ipv 


6only=[onloffjlsslj]j]; 
默认 : listen 80; 
配置 块 : server 


listen 参 数 决定 Nginx 服 务 如 何 监听 端口 。 在 listen 后 可 以 只 加 IP 地 
址 、 端 口 或 主机 名 ， 非 党 灵活， 例如 ; 


listen 127.0.0.1:8000 
listen 127.0.0.1; # 注 意 : 不 加 端口 时 ， 默 认 监听 


80 端 口 


listen 8000; 
listen *:8000; 
listen localhost:8000; 


如 果 服 务 器 使 用 IPv6 地 址 ， 那 么 可 以 这 样 使 用 : 


listen [::]: 6896 1 
listen Dt :1 
listen [:::a8c9: 1 80; 


在 地 址 和 端口 后 ， 还 可 以 加 上 其 他 参数 ， 例 如 : 


listen 443 default_ server ssl; 
listen 127.0.0.1 default_ server accept filter=dataready backlog=1024; 


下 面 说 明 listen 可 用 参数 的 意义 。 


-default: 将 所 在 的 server 块 作为 整个 web 服 务 的 默认 server 块 。 如 采 
没有 设置 这 个 参数 ， 那 么 将 会 以 在 nginx.conf 中 找到 的 第 一 个 server 块 作 
为 默认 server 块 。 为 什么 需要 默认 虚拟 主机 呢 ? 当 一 个 请 求 无 法 匹配 配 
置 文件 中 的 所 有 主机 域名 时 ， 束 会 选用 默认 的 虚拟 主机 (在 11.3 市 介绍 
默认 主机 的 使 用 ) 。 


default server: 同上 。 


:backlog=num: 表示 TCP 中 backlog 队 列 的 大 小 。 默 认为 -1， 表 示 不 
予 设置 。 在 TCP 建 立 三 次 握手 过 程 中 ， 进 程 还 没有 开始 处 理 监 听 句 柄 ， 
这 时 backlog 队 列 将 会 放置 这 些 新 连接 。 可 如 果 backlog 队 列 已 满 ， 还 有 
新 的 客户 端 试 图 通过 三 次 握手 建立 TCP 连 接 ， 这 时 客户 端 将 会 建立 连接 
失败 。 


Tcvbuf=size: 设置 监听 句柄 的 SO_RCVBUF 参 数 。 
:sndbuf=size: 设置 监听 句柄 的 SO_SNDBUF 人 参数。 
accept_filter: 设置 accept 过 滤器 ， 只 对 FreeBSD 控 作 系 统 有 用 。 


-deferred: 在 设置 该 参数 后 ， 大 用 户 发 起 建立 连接 请 求 ， 并 且 完 成 
了 TCP 的 三 次 握手 ， 内 核 也 不 会 为 了 这 次 的 连接 调度 workerj 进 程 来 处 
理 ， 只 有 用 户 真 的 发 送 请 求 数据 时 (内 核 已 经 在 网 卡 中 收 到 请 求 数据 
包 ) ， 内 核 才 会 唤醒 worker 进 程 处 理 这 个 连接 。 这 个 参数 适用 于 大 并 发 
的 情况 下 ， 它 减轻 了 worker 进 程 的 负担 。 当 请 求 数据 来 临时 ，worker 进 
程 才 会 开始 处 理 这 个 连 授 。 只 有 确认 上 面 所 说 的 应 用 场景 符合 自己 的 
业务 需求 时 ， 才 可 以 使 用 deferred 配 置 。 


bind:， 绑 定 当 前 端口 /地 址 对 ， 如 127.0.0.1:8000。 只 有 同时 对 一 个 
端口 监听 多 个 地 址 时 才 会 生效 。 


ssl: 在 当前 监听 的 端口 上 建立 的 连接 必须 基于 SSL 协 议 。 


(2) 主机 名 称 


语法 : server_name name[...]: 


LL 
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时 i 人 人: server name 
配置 块 : server 


server_name 后 可 以 跟 多 个 主机 名 称 ， 如 server_name 


wwwi.testweb.com 、download.testweb.com;。 


在 开始 处 理 一 个 HTTP 请 求 时 ，Nginx 会 取出 header 头 中 的 Host， 与 
每 个 server 中 的 server_name 进 行 匹 配 ， 以 此 决定 到 底 由 哪 一 个 server 块 
来 处 理 这 个 请 求 。 有 可 能 一 个 Host 与 多 个 server 块 中 的 server_name 都 匹 
配 ， 这 时 束 会 根据 匹配 优先 级 来 选择 实际 处 理 的 server 块 。server_name 
与 Host 的 匹配 优先 级 如 下 : 


1) 首先 选择 所 有 字符 串 完全 匹配 的 server_name， 如 


www.testweb.com 。 
2) 其 次 选择 通配符 在 前 面 的 server_ name， 如 *.testweb.com 。 
3) 再 次 选择 通配符 在 后 面 的 server_ name， 如 www.testweb.* 。 


4) 最 后 选择 使 用 正则 表达 式 才 匹配 的 server_name， 如 


~AM\.testweb\.com$ ° 


实际 上 ， 这 个 规则 正 是 7.7 万 中 介绍 的 吝 通 配 符 散 列表 的 实现 依 
据 ， 同 时 ， 在 10.4 世 也 介绍 了 虚拟 主机 配置 的 管理 。 如 果 Host 与 所 有 的 
server_name 都 不 匹配 ， 这 时 将 会 按 下 列 顺序 选择 处 理 的 server 抉 。 


1) 优先 选择 在 listen 配 置 项 后 加 入 [defaultldefault_server] 的 server 
块 。 


2) 找到 死 配 listen 妆 口 的 第 一 个 server 块 。 


如 果 server_name 后 跟着 空 字符 串 (如 server_name"";) ， 那 么 表示 
匹配 没有 Host 这 个 HTTP 头 部 的 请 求 。 


@@ 注意 “Nginx 正 是 使 用 server_ name 配置 项 针对 特定 Host 域 名 的 
请 求 提供 不 同 的 服务 ， 以 此 实现 虚拟 主机 功能 。 


(3) server_ names_hash _ bucket size 
语法 : server_names_hash_bucket_size size: 
天 i 从 : server_ names_hash_ bucket_size 32|64|128; 
配置 块 : http、server、]location 


为 了 提高 快速 寻找 到 相应 server name 的 能 力 ，Nginx 使 用 散 列 表 来 
存储 server name 。server_names_hash_bucket_ size 设 置 了 每 个 散 列 桶 占 
用 的 内 存 大 小 。 


(4) server names hash max size 
语法 : server_names_hash_max_size size; 
办: server names hash max size 512: 
配置 块 : http、server、location 


server_names_hash_max_size 会 影响 散 列 表 的 冲突 率 。 
server_names_hash_max_size 越 大 ， 消 耗 的 内 存 就 越 多 ， 但 散 列 key 的 冲 
突 率 则 会 降低 ， 检 索 速 度 也 更 快 。server_names_hash_max_size 越 小 ， 
消耗 的 内 存 就 越 小 ， 但 散 列 key 的 冲突 率 可 能 增高 。 


(5) 重 定向 主机 名 称 的 处 理 


语法 :，server_name_in_redirect on|off; 
Ri 人 \: server name in redirect on: 
配置 块 : http、server 或 者 location 


该 配置 需要 配合 server_name 使 用 。 在 使 用 on 打开 时 ， 表 示 在 重 定 
向 请 求 时 会 使 用 server_name 里 配置 的 第 一 个 主机 名 代替 原先 请 求 中 的 
Host 关 部， 而 使 用 of 关闭 时 ， 表 示 在 重 定 同 请 求 时 使 用 请 求 本 里 的 
Host 头 部 。 


(6) location 
语法 : location[=|~|~#|Av|@]Auri{…} 
配置 块 : server 
location 会 莹 试 根据 用 户 请 求 中 的 URI 来 匹配 上 面 的 /uri 表 达 式 ， 如 
果 可 以 匹配 ， 职 选择 location{} 块 中 的 配置 来 处 理 用 户 请 求 。 当 然 ， 匹 
配方 式 是 多 样 的 ， 下 面 介绍 location 的 匹配 规则 。 
1) = 表示 把 URI 作 为 字符 串 ， 以 便 与 参数 中 的 uri 做 完全 匹配 。 例 


如 : 


location =/f{ 
寺 求 


1 ;者 < 上 且 
# 只 有 当 十 冰雹 


Ee 


/时 ， 才 会 使 用 该 


location 下 的 配 


2) ~ 表示 匹配 URI 时 是 字母 大 小 写 敏 感 的 。 
3) ~* 表 示 匹 配 URI 时 忽略 字母 大 小 写 问 题 。 
4) 人 表示 匹配 URI 时 只 需要 其 前 半 部 分 与 uri 参 数 匹 配 即 可 。 例 


如 : 


location 人 ^~ /images/ { 
# 以 


/images/ 开 始 的 请 求 都 会 匹配 上 


5) @ 表 示 仅 用 于 Nginx 服 务 内 部 请 求 之 间 的 重 定 向 ， 带 有 @ 的 
location 不 直接 处 理 用 户 请 求 。 


当然 ， 在 uri 参 数 里 是 可 以 用 正则 表达 式 的 ， 例 如 : 


location ~* \.(gif|jpgljpeg)$ { 
# 匹配 以 


, jpeg 结尾 的 请 求 


注意 ，location 是 有 顺序 的 ， 当 一 个 请 求 有 可 能 匹配 多 个 location 
时 ， 实 际 上 这 个 请 求 会 被 第 一 个 location 处 理 。 


在 以 上 各 种 死 配方 式 中 ， 都 只 能 表达 为 “如 果 匹 配 .…. 则 .……”。 如 果 需 
要 表达 “如 果 不 匹 配 ... 则 ...”， 就 很 难 直 接 做 到 。 有 一 种 解决 方法 是 在 最 
后 一 个 location 中 使 用 /作为 参数 ， 它 会 匹配 所 有 的 HTTP 请 求 ， 这 样 就 


可 以 表示 如 果 不 能 匹配 前 面 的 所 有 location， 则 由 “这 个 location 处 理 。 
例如 : 


location /ff{ 


# /可 以 匹配 所 有 请 求 


2.4.2 ”文件 路 径 的 定义 


下 面 介绍 一 下 文件 路 径 的 定义 配置 项 。 
(1) 以 root 方 式 设置 资源 路 径 
语法 : root path; 
默认 : root html; 
配置 块 : http、server、]location、 让 
例如 ， 定 义 资 源 文件 相对 于 HTTP 请 求 的 根 目录 。 


location /download/ { 
root /opt/web/html/; 
} 


在 上 面 的 配置 中 ， 如 果 有 一 个 请 求 的 URI 
是 /download/index/test.html， 那 么 Web 服 务 絮 将 会 返回 服务 妖 


上 /opt/web/html/download/index/test.html 文 件 的 内 容 。 
(2) 以 alias 方 式 设置 资源 路 径 
语法 : alias path; 


配置 块 : location 


alias 也 是 用 来 设置 文件 资源 路 径 的 ， 它 与 root 的 不 同 点 主要 在 于 如 
何 解读 紧 跟 location 后 面 的 uri 参 数 ， 这 将 会 致使 alias 与 root 以 不 同 的 方式 
将 用 户 请 求 映 射 到 真正 的 磁盘 文件 上 。 例 如 ， 如 果 有 一 个 请 求 的 URI 
是 /confmnginx.conf， 而 用 户 实际 想 访问 的 文件 
在 /usr/local/nginx/conf/nginx.conf， 那 么 想 要 使 用 alias 来 进行 设置 的 话 ， 
可 以 采用 如 下 方式 : 


location /conf { 
alias /usr/local/nginx/conf/; 


} 


如 采用 root 设 置 ， 那 么 语句 如 下 所 示 : 


location /conf { 
root /usr/local/nginx/; 
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使 用 alias 时 ， 在 URI 癌 实际 文件 路 径 的 映射 过 程 中 ， 已 经 把 location 
后 配置 的 /conf 这 部 分 字符 串 丢 弃 挥 ， 因 此 ，/conf/nginx.conf 请 求 将 根据 
alias path 了 映射 为 path/nginx.conf。root 则 不 然 ， 它 会 根据 完整 的 URI 请 求 
来 上 映射， 因此，/conf/nginx.conf 请 求 会 根据 root path 映 射 为 
path/conf/nginx.conf。 这 也 是 root 可 以 放置 到 http、server、location 或 if 块 
中 ， 而 alias 只 能 放置 到 ]ocation 块 中 的 原因 。 


alias 后 面 还 可 以 添加 正则 表达 式 ， 例 如 : 


location ~ ^/test/(\w+)\.(\w+)$ { 
alias /usr/local/nginx/$2/$1.$2; 
} 


这 样 ， 请 求 在 访问 /test/nginx.conf 上 时 ，Nginx 会 返 


回 /usr/local/nginx/conf/nginx.conf 文 件 中 的 内 容 。 
(3) 访问 首页 
语法 : index file...: 
默认 :， index index.html; 
配置 块 : http、server、]location 


有 了 时， 访问 站 点 时 的 URI 是 /， 这 时 一 般 是 返回 网 站 的 首页 ， 而 这 
与 root 和 alias 都 不 同 。 这 里 用 ngx_http_index_module 模 块 提供 的 index 配 


置 实现 。index 后 可 以 跟 多 个 文件 参数 ，Nginx 将 会 按照 顺序 来 访问 这 些 
文件 ， 例 如 : 


location / { 

root path 

index /index. html /html/index.php /index.php; 
} 


接收 到 请 求 后 ，Nginx 首 移 会 尝试 访问 pathindex.php 文 件 ， 如 果 可 
以 访问 ， 束 直接 返回 文件 内 容 结束 请 求 ， 否 则 再 试图 返回 
pathhtmlyindex.php 文 件 的 内 容 ， 依 此 类 推 。 


(4) 根据 HTTP 返 回 码 重 定向 页 面 
语法 :，error_page code[code...][=|=answer-codejuril@named_location 
配置 块 : http、server、]location、 证 


当 对 于 某 个 请 求 返回 错误 码 时 ， 如 果 匹 配 上 了 error_page 中 设置 的 
code， 则 重 定向 到 新 的 URI 中 。 例 如 : 


error_page 404 /404.html; 

error_page 502 503 504 /50x.html; 

error_page 403 http://example.com/forbidden.html 
/ 

error_page 404 = @fetch; 


注意 ， 虽 然 重 定向 了 URI， 但 返回 的 HTTP 错 误 码 还 是 与 原来 的 相 
同 。 用 户 可 以 通过 “=” 来 更 改 返 回 的 错误 码 ， 例 如 : 


error_page 404 =200 /empty ,gif， 
error_page 404 =403 /forbidden.gif; 


也 可 以 不 指定 确切 的 返回 错误 码 ， 而 是 由 重 定 同 后 实际 处 理 的 真 
实 结果 来 决定 ， 这 时 ， 只 要 把 “=” 后 面 的 错误 码 去 挥 即 可 ， 例 如 : 


error_page 404 = /empty ,gif， 


如 有 条 不 想 修 改 URI， 只 是 想 让 这 样 的 请 求 重 定 同 到 另 一 个 location 
中 进行 处 理 ， 那 么 可 以 这 样 设置 : 


Location / ( 
error_page 404 @fallback; 


) 
location @fallback ( 
proxy_pass http://backend 


这 样 ， 返 回 404 的 请 求 会 被 反问 代理 到 http://backend 上 游 服务 右 中 
处 理 。 


(5) 是 否 允 许 递 归 使 用 error_page 
语法 :，recursive_error_pages[onloff]; 
默认 :，recursive_error_pages off; 


配置 块 : http、server、location 


确定 是 否 人 允许 递归 地 定义 error_ page。 
(6) try_files 

语法 : try_files path1[path2]uri; 

配置 块 : server、]location 


try_files 后 要 跟 若 干 路 径 ， 如 pathl path2...， 而 且 最 后 必须 要 有 uri 
参数 ， 意 义 如 下 : 党 试 按照 顺序 访问 每 一 个 path， 如 果 可 以 有 效 地 读 
取 ， 就 直接 向 用 户 返 回 这 个 path 对 应 的 文件 结束 请 求 ， 否 则 继续 向 下 访 
问 。 如 果 所 有 的 path 都 找 不 到 有 效 的 文件 ， 就 重 定向 到 最 后 的 参数 uri 
上 。 因 此 ， 最 后 这 个 参数 uri 必 须 存 在 ， 而 且 它 应 该 是 可 以 有 效 重 定向 
的 。 例 如 : 


try_files /system/maintenance.html $uri $uri/index.html $uri,html @other; 
location @other { 
proxy_pass http://backend 


上 面 这 上 段 代码 表示 如 果 前 面 的 路 径 ， 如 /system/maintenance.html 
等 ， 都 找 不 到 ， 束 会 反 疝 代理 到 http://backend 服务 上 。 还 可 以 用 指定 
错误 码 的 方式 与 error_page 配 合 使 用 ， 例 如 : 


location / { 
try_files $uri $uri/ /error.phpc=404 =404; 


2.4.3 内存 及 磁 僵 换 源 的 分 配 


下 面 介绍 处 理 请 求 时 内 存 、 磁 副 资 源 分 配 的 配置 项 。 
(1) HTTP 包 体 只 存储 到 磁 副 文件 中 

语法 : client_body_in_file_only onlcleanloff; 

默认 :， client_ body_in file_only off; 

配置 块 : http、server、]location 


当 值 为 非 off 时 ， 用 户 请 求 中 的 HTTP 包 体 一 律 存储 到 磁盘 文件 中 ， 
即使 只 有 0 字 节 也 会 存储 为 文件 。 当 请 求 结束 时 ， 如 果 配 置 为 on， 则 这 
个 文件 不 会 被 删除 〈 该 配置 一 般 用 于 调试 、 定 位 问题 ) ， 但 如 有 果 配 置 
为 clean， 则 会 删除 该 文件 。 


(2) HTTP 包 体 尽 量 写 入 到 一 个 内 存 buffer 中 
语法 : dlient_body_in_single_buffer onloff; 
默认 :client_body_in_single_buffer off; 


配置 块 : http、server、]location 


用 户 请 求 中 的 HTTP 包 体 一 律 存储 到 内 存 buffer 中 。 当 然 ， 如 果 
HTTP 包 体 的 大 小 超过 了 下 面 client_body_buffer_size 设 置 的 值 ， 包 体 还 
是 会 写 入 到 磁盘 文件 中 。 


(3) 存储 HTTP 头 部 的 内 存 buffer 大 小 
语法 : dlient_header_buffer size size; 
默认 : client header buffer size 1k: 
配置 块 : http 、server 


上 面 配置 项 定义 了 正常 情况 下 Nginx 接 收 用 户 请 求 中 HTTP header 
部 分 (包括 HTTP 行 和 HTTP 头 部 ) 时 分 配 的 内 存 buffer 大 小 。 有 时 ， 请 
求 中 的 HTTP header 部 分 可 能 会 超过 这 个 大 小 ， 这 时 


large_client_header_buffers 定 义 的 buffer 将 会 生效 。 
(4) 存储 超大 HTTP 头 部 的 内 存 buffer 大 小 
语法 : large_client_header_buffers number size:; 
默认 :large_client_header_buffers 48k; 


配置 块 : http、server 


large_client_header_buffers 定 义 了 Nginx 接 收 一 个 超大 HTTP 头 部 请 
求 的 buffer 个 数 和 每 个 buffer 的 大 小 。 如 采 HTTP 请 求 行 (如 GET/index 
HTTP/1.1) 的 大 小 超过 上 面 的 单个 buffer， 则 返回 "Request URI too 
large"(414)。 请 求 中 一 般 会 有 许多 header， 每 一 个 header 的 大 小 也 不 能 超 
过 单个 buffer 的 大 小 ， 否 则 会 返回 "Bad request"(400)。 当 然 ， 请 求 行 和 
请 求 头 部 的 总 和 也 不 可 以 超过 buffer 个 数 *buffer 大 小 。 


(5) 存储 HTTP 包 体 的 内 存 buffer 大 小 \ 
语法 : ”dlient_body_buffer_size size; 
默认 :， client_body_buffer size 8k/16k: 
配置 块 : http、server、location 


上 面 配置 项 定义 了 Nginx 接 收 HTTP 包 体 的 内 存 缓冲 区 大 小 。 也 就 
是 说 ，HTTP 包 体会 先 接收 到 指定 的 这 块 缓存 中 ， 之 后 才 决 定 是 否 写 入 
磁 盟 。 


@ 注意 ”如 果 用 户 请 求 中 含有 HTTP 浆 部 ContenLLength， 并 且 其 
标识 的 长 度 小 于 定义 的 buffer 大 小 ， 那 么 Nginx 会 自动 降低 本 次 请 求 所 
使 用 的 内 存 buffer， 以 降低 内 存 消耗 。 


(6) HTTP 包 体 的 临时 存放 目录 


语法 : client_body_temp_path dir-path[level1[level2[level3]]] 
默认 : client_ body_temp_path client_body_temp; 
配置 块 : http、server、]location 


上 面 配置 项 定义 HTTP 包 体 存放 的 临时 目录 。 在 接收 HTTP 包 体 
时 ， 如 果 包 体 的 大 小 大 于 client_body_buffer_size， 则 会 以 一 个 递增 的 整 
数 命 名 并 存放 到 dlient_body_temp_path 指 定 的 目录 中 。 后 面 跟 着 的 
levell、level2、level3， 是 为 了 防止 一 个 目录 下 的 文件 数量 太 多 ， 从 而 
导致 性 能 下 降 ， 因 此 使 用 了 level 参 数 ， 这 样 可 以 按照 临时 文件 名 最 多 
再 加 三 层 目 录 。 例 如 : 


client_body_ temp_path /opt/nginx/client temp 1 2; 


如 果 新 上 传 的 HTTP 包 体 使 用 00000123456 作 为 临时 文件 名 ， 就 会 
被 存放 在 这 个 目录 中 。 


/opt/nginx/client_ temp/6/45/00000123456 
(7) connection pool size 
语法 ; connection_pool_size size; 


默认 : connection_pool]_size 256; 


配置 块 : http、server 


Nginx 对 于 每 个 建立 成 功 的 TCP 连 接 会 预 完 分 配 一 个 内 存 池 ， 上 面 
的 size 配 置 项 将 指定 这 个 内 存 池 的 初始 大 小 〈 即 ngx_connection_t 结 构 体 
中 的 pool 内 存 池 初始 大 小 ，9.8.1 广 将 介绍 这 个 内 存 池 是 何 时 分 配 的 ) ， 
用 于 减少 内 核对 于 小 块 内 存 的 分 配 次 数 。 需 慎重 设置 ， 因 为 更 大 的 size 
会 使 服务 絮 消 耗 的 内 存 增多 ， 而 更 小 的 size 则 会 引发 更 多 的 内 存 分 配 次 
Ro 


(8) request_pool_ size 
语法 : ”request_pool_size size; 
默认 :request_pool_size 4k:; 


配置 块 : http、server 


Nginx 开 始 处 理 HTTP 请 求 时 ， 将 会 为 每 个 请 求 都 分 配 一 个 内 存 
池 ，size 配 置 项 将 指定 这 个 内 存 池 的 初始 大 小 〈 即 ngx_http_request t 结 
构 体 中 的 pool 内 存 池 初 始 大 小 ，11.3 节 将 介绍 这 个 内 存 池 是 何 时 分 配 
的 ) ， 用 于 减少 内 核对 于 小 块 内 存 的 分 配 次 数 。TCP 连 接 关闭 时 会 销毁 
connection_pool_size 指 定 的 连接 内 存 池 ，HTTP 请 求 结束 时 会 销毁 
request_pool_size 指 定 的 HTTP 请求 内 存 池 ， 但 它们 的 创建 、 销 毁 时 间 并 


不 一 致 ， 因 为 一 个 TCP 连 接 可 能 被 复 用 于 多 个 HTTP 请 求 。8.7 世 会 详 述 
内 存 池 原理 。 


2.4.4 网 络 连接 的 设置 


中 ， 如 果 在 一 个 时 间 间 隔 
， 则 认为 超时 ， 并 向 客户 端 返回 408("Request timed out") 响 应 。 


下 面 介 绍 网络 连 接 的 设置 配置 项 。 

(1) 读 取 HTTP 头 部 的 超时 时 间 
语法 : ”dlient_header_timeout time 〈 默 认 单 位 : 秒 ) ; 
默认 :client_header_timeonut 60; 


配置 块 : http、server、]location 


客户 端 与 服务 器 建立 连接 后 将 开始 接收 HTTP 头 部 ， 在 这 个 过 程 
(超时 时 间 ) 内 没有 读 取 到 客户 端 发 来 的 字 


(2) 读 取 HTTP 包 体 的 超时 时 间 
语法 : ”dlient_body_timeout time (默认 单位 ， 秒 ) ; 
默认 :， dlient_body_timeout 60; 


配置 块 : http、server、location 


此 配置 项 与 client_header_timeout 相 似 ， 只 是 这 个 超时 时 间 只 在 读 
取 HTTP 包 体 时 才 有 效 。 


(3) 发 送 响应 的 超时 时 间 
语法 : ”send_timeout time; 
默认 :， send_timeout 60; 
配置 块 : http、server、]location 


这 个 超时 时 间 是 发 送 响应 的 超时 时 间 ， 即 Nginx 服 务 器 回 客 户 端 发 
送 了 数据 包 ， 但 客户 端 一 直 没 有 去 接收 这 个 数据 包 。 如 采 某 个 连接 超 
过 send_timeout 定 义 的 超时 时 间 ， 那 么 Nginx 将 会 关闭 这 个 连接 。 


(4) reset_timeout_connection 
语法 : reset_timeout_connection on|off; 
默认 :， reset_timeout_connection off:; 
配置 块 : http、server、location 


连接 超时 后 将 通过 向 客户 端 发 送 RST 包 来 直接 重 置 连接 。 这 个 选项 
打开 后 ，Nginx 会 在 某 个 连接 超时 后 ， 不 是 使 用 正 滑 情形 下 的 四 次 握手 
关闭 TCP 连 接 ， 而 是 直接 向 用 户 发 送 RST 重 置 包 ， 不 再 等 竺 用户 的 应 


答 ， 直 接 释 放 Nginx 服 务 器 上 关于 这 个 套 接 字 使 用 的 所 有 缓存 (如 TCP 
滑动 窗口 ) 。 相 比 正常 的 关闭 方式 ， 它 使 得 服务 器 避免 产生 许多 处 于 
FIN_WAIT_1、FIN_WAIT 2、TIME_WAIT 状 态 的 TCP 连 接 。 


注意 ， 使 用 RST 重 置 包 关闭 连接 会 带 来 一 些 问题 ， 默 认 情况 下 不 会 
开启 。 


(5) lingering_close 
语法 : lingering_close offlon|always; 
BR: lingering_close on; 
配置 块 : http 、server 、l]ocation 


该 配置 控制 Nginx 关 闭 用 户 连 接 的 方式 。always 表 示 关 闭 用 户 连 接 
前 必须 无 条 件 地 处 理 连 接 上 所 有 用 户 发 送 的 数据 。off 表 示 天 闭 连接 时 
完全 不 管 连接 上 古人 否 已 经 有 准备 束 绪 的 来 日 用 户 的 数据 。on 是 中 间 
值 ， 一 般 情 况 下 在 关闭 连接 前 都 会 处 理 连接 上 的 用 户 发 送 的 数据 ， 除 
了 有 些 情况 下 在 业务 上 认定 这 之 后 的 数据 是 不 必要 的 。 


(6) lingering_time 
语法 : lingering_time time; 


默认 : lingering_time 30s; 


配置 块 : http、server、]location 


lingering_close 启 用 后 ， 这 个 配置 项 对 于 上 传 大 文件 很 有 用 。 上 文 
讲 过 ， 当 用 户 请 求 的 Content-Length 大 于 max_client_body_size 配 置 时 ， 
Nginx 服 务 会 立刻 向 用 户 发 送 413 (Request entity too large) 响应 。 但 
和 是， 很 多 客户 病 可 能 不 管 413 返 回 值 ， 仍 然 持续 不 断 地 上 传 HTTP 
body， 这 时 ， 经 过 了 lingering_time 设 置 的 时 间 后 ，Nginx 将 不 管用 户 是 
否 仍 在 上 传 ， 都 会 把 连接 关闭 掉 。 


(7) lingering_timeout 
语法 : lingering_timeout time; 
默认 :， lingering_timeout 5s; 


配置 块 : http、server、]location 


lingering_close 生 效 后 ， 在 关闭 连接 前 ， 会 检测 是 人 否 有 用 户 发 送 的 
数据 到 达 服 务 器 ， 如 果 超 过 lingering_timeout 时 间 后 还 没有 数据 可 读 ， 
束 直 接 关 闭 连 接 ; 否则， 必须 在 读 取 完 连 接 缓 冲 区 上 的 数据 并 丢弃 挥 
后 可 会 天 财 连 翁 。 


(8) 对 某 些 浏览 器 禁用 keepalive 功 能 


语法 : keepalive_disable[msie6lsafarilnone].. 


默认 :， keepalive_disablemsie6 safari 
配置 块 : http、server、]location 


HTTP 请 求 中 的 keepalive 功 能 是 为 了 让 多 个 请 求 复 用 一 个 HTTP 长 连 
接 ， 这 个 功能 对 服务 器 的 性 能 提高 是 很 有 帮助 的 。 但 有 些 浏览 器 ， 如 
IE 6 和 Safari， 它 们 对 于 使 用 keepalive 功 能 的 POST 请 求 处 理 有 功能 性 问 
题 。 因 此 ， 针 对 正 6 及 其 早期 版 本 、Safari 浏 览 右 默认 是 禁用 keepalive 


(9) keepalive 超 时 时 间 
语法 : keepalive_timeout time (默认 单位 ， 秒 ) ; 
默认 :keepalive_timeout 75; 
配置 块 : http、server、]location 


一 个 keepalive 连 接 在 闲置 超过 一 定时 间 后 (默认 的 是 75 秒 ) ， 服 务 
郝 和 浏览 套 都 会 去 关闭 这 个 连接 。 当 然 ，keepalive_timeout 配 置 项 是 用 
来 约束 Nginx 服 务 絮 的 ，Nginx 也 会 按照 规 施 把 这 个 时 间 传 给 浏览 器 
但 每 个 浏览 器 对 待 keepalive 的 策略 有 可 能 是 不 同 的 。 


(10) 一 个 keepalive 长 连接 上 人 允许 承载 的 请 求 最 大 数 


语法 : keepalive_requests ni 


默认 :keepalive_requests 100; 

配置 块 : http、server、]location 

一 个 keepalive 连 接 上 稚 认 最 多 只 能 发 送 100 个 请 求 。 
(11) tcp_nodelay 

语法 : tcp_nodelay onloff; 

默认 : tcp_nodelay on; 

配置 块 : http、server、location 

确定 对 keepalive 连 接 是 否 使 用 TCP_NODELAY 选 项 。 
(12) tcp_nopush 

语法 : tcp_nopush onloff; 

默认 : tcp_nopush off; 

配置 块 : http、server、location 


在 打开 sendfile 选 项 时 ， 确 定 是 否 开局 FreeBSD 系 统 上 的 
TCP_NOPUSH 或 Linux 系 统 上 的 TCP_CORK 功 能 。 打 开 tcp_nopush 后 ， 
将 会 在 发 送 啊 应 时 把 整个 啊 应 包头 放 到 一 个 TCP 包 中 发 送 。 


2.4.5 MIME 类 型 的 设置 


下 面 是 MIME 类 型 的 设置 配置 项 。 
MIME type 与 文件 扩展 的 映射 
语法 : type{.}; 

配置 块 : http 、server 、location 


定义 MIME type 到 文件 扩展 名 的 映射 。 多 个 扩展 名 可 以 映射 到 同一 


个 MIME type。 例 如 : 


types { 
text/html html; 
text/html Conf ， 
image/gif gif; 
image/jpeg jpg; 


.默认 MIME type 

语法 : default_type MIME-type; 
默认 :， default_type text/plain; 
配置 块 : http、server、]location 


当 找 不 到 相应 的 MIME type 与 文件 扩展 名 之 间 的 映射 时 ， 使 用 默认 
的 MIME type 作 为 HTTP header 中 的 Content-Type。 


‘types_hash_bucket_ size 

语法 : types_hash_bucket_size size; 
默认 :，types_hash_bucket_size 32|64|128; 
配置 块 http、server、location 


为 了 快速 寻找 到 相应 MIME type，Nginx 使 用 散 列 表 来 存储 MIME 
type 与 文件 扩展 名 。types_hash_bucket_size 设 置 了 每 个 散 列 桶 占用 的 内 
存 大 小 。 


‘types_hash max_size 

语法 : types_hash_max_size size:; 
默认 :，types_hash_max_size 1024; 
配置 块 : http、server、]location 


types_hash_max_size 影 啊 散 列 表 的 神 突 率 。types_hash_max_size 越 
大 ， 就 会 消耗 更 多 的 内 存 ， 但 散 列 key 的 冲突 率 会 降低 ， 检 索 速度 就 更 
快 。types_hash_max_size 越 小 ， 消 耗 的 内 存 就 越 小 ， 但 散 列 key 的 冲突 
率 可 能 上 升 。 


2.4.6 ”对 客户 端 请 求 的 限制 


下 面 介绍 对 客户 瘦 请 求 的 限制 的 配置 项 。 
(1) 按 HTTP 方 法 名 限制 用 户 请 求 
语法 : limit_except method...{...} 


配置 块 : location 


Nginx 通 过 limit_except 后 面 指 定 的 方法 名 来 限制 用 户 请 求 。 方 法 名 
可 取 值 包括 : GET、HEAD、POST、PUT、DELETE、MKCOL 、 
COPY ~ MOVE ~ OPTIONS ~ PROPFIND ~ PROPPATCH ~ LOCK 、\ 
UNLOCK 或 者 PATCH。 例 如 : 


limit_ except GET { 
allow 192.168.1.0/32; 
deny all; 

. 


注意 ， 人 允许 GET 方 法 就 意味 着 也 允许 HEAD 方 法 。 因 此 ， 上 面 这 段 
代码 表示 的 是 禁止 GET 方 法 和 HEAD 方 法 ， 但 其 他 HTTP 方 法 是 允许 
的 。 


(2) HTTP 请 求 包 体 的 最 大 值 
语法 : client_max_body_size size; 


RR: client_max_body_size 1m; 


配置 块 : http、server、location 


浏览 器 在 发 送 含有 较 大 HITP 包 体 的 请 求 时 ， 其 头 部 会 有 一 个 
Content-Length 字 段 ，client_max_body_size 是 用 来 限制 Content-Length 所 
示 值 的 大 小 的 。 因 此 ， 这 个 限制 包 体 的 配置 非常 有 用 处 ， 因 为 不 用 等 
Nginx 接 收 完 所 有 的 HTTP 包 体 一 一 这 有 可 能 消耗 很 长 时 间 一 一 就 可 以 
告诉 用 户 请 求 过 大 不 被 接受 。 例 如 ， 用 户 试图 上 传 一 个 10GB 的 文件 ， 
Nginx 在 收 完 包头 后 ， 发 现 Content-Length 超 过 dlient_max_body_size 定 义 


的 值 ， 就 直接 发 送 413("Request Entity Too Large") 啊 应 给 客户 端 。 
(3) 对 请 求 的 限 速 
语法 : limit_rate speed:; 
默认 : limit_rate 0; 
配置 块 : http、server、]location、 让 


此 配置 是 对 客户 端 请 求 限制 每 秒 传输 的 字 世 数 。speed 可 以 使 用 
2.2.4 订 中 提 到 的 多 种 单位 ， 默 认 参 数 为 0， 表 示 不 限 速 。 


针对 不 同 的 客户 端 ， 可 以 用 $limit_rate 参 数 执行 不 同 的 限 速 策略 。 
例如 : 
server { 


if ($slow) { 
set $1limit_rate 4k; 


(4) limit_ rate_after 
语法 : 1limit rate_after time:; 
默认 : limit rate_after 1m:; 
配置 块 : http、server、]location、 让 


此 配置 表示 Nginx 加 客户 端 发 送 的 响应 长 度 超过 limit_rate_after 后 才 
开始 限 速 。 例 如 : 


limit_rate after i1m; 
limit_rate 100k; 


11.9.2 市 将 从 源码 上 介绍 limit_rate_after 与 limit_rate 的 区 别 ， 以 及 
HTTP 框 架 是 如 何 使 用 它们 来 限制 发 送 啊 应 速度 的 。 


2.4.7 文件 操作 的 优化 


下 面 介绍 文件 操作 的 优化 配置 项 。 
(1) sendfile 系 统 调用 


语法 : sendfile onloff; 


默认 : sendfile off; 
配置 块 : http、server、]location 


可 以 局 用 Linux 上 的 sendfile 系 统 调用 来 发 送 文 件 ， 它 减少 了 内 核 态 


与 用 户 态 之 间 的 两 次 内 存 复制 ， 这 样 就 会 从 磁盘 中 读 取 文件 后 直接 在 
内 核 态 发 送 到 网 卡 设备 ， 提 高 了 发 送 文件 的 效率 。 


(2) AIO 系 统 调 用 
语法 : aio onloff; 
默认 : aio off; 
配置 块 : http、server、location 


此 配置 项 表示 是 否 在 FreeBSD 或 Linux 系 统 上 启用 内 核 级 别 的 异步 


文件 1/O 功 能 。 注 意 ， 它 与 sendfile 功 能 是 互 不 的 。 


(3) directio 
语法 : ”directio sizel|off; 
默认 : directio off; 


配置 块 : http、server、location 


此 配置 项 在 FreeBSD 和 Linux 系 统 上 使 用 O_DIRECT 选 项 去 读 取 文 
件 ， 绥 冲 区 大 小 为 size， 通 常 对 大 文件 的 读 取 速 度 有 优化 作用 。 注 意 ， 
它 与 sendfile 功 能 是 互 不 的 。 


(4) directio_alignment 
语法 : directio_alignment size; 
默认 : directio_alignment 512; 


配置 块 : http、server、]location 


它 与 directio 配 合 使 用 ， 指 定 以 directio 方 式 读 取 文 件 时 的 对 齐 方 
式 。 一 般 情况 下 ，512B 已 经 足够 了 ， 但 针对 一 些 高 性 能 文件 系统 ， 如 
Linux 下 的 XFS 文件 系统 ， 可 能 需要 设置 到 4KB 作 为 对 齐 方 式 。 


(5) 打开 文件 缓存 
语法 : open_file_cache max=N[inactive=time]loff; 
默认 :_ open_file_cache off; 


配置 块 : http、server、]location 


文件 缓存 会 在 内 存 中 存储 以 下 3 种 信息 : 


文件 句柄 、 文 件 大 小 和 上 次 修改 时 间 。 


已 经 打开 过 的 目 示 纺 梅 。 


没有 找到 的 或 者 没有 权限 操作 的 文件 信息 。 


这 样 ， 通 过 读 取 缓 存 束 减 少 了 对 位 强 的 操作 。 


该 配置 项 后 面 跟 3 种 参数 。 


:max: 表示 在 内 存 中 存储 元 素 的 最 大 个 数 。 当 达到 最 大 限制 数量 
后 ， 将 采用 LRU (Least Recently Used) 算法 从 缓存 中 淘汰 最 近 最 少 使 
用 的 元 素 。 


-inactive: 表示 在 inactive 指 定 的 时 间 段 内 没有 人 被 访问 过 的 元 素 将 会 
被 淘汰 。 默 认 时 间 为 60 秒 。 


off: 关闭 缓 存 功能 。 

例如 : 

open_file_cache max=1000 inactive=20s; 
(6) 是 否 缓存 打开 文件 错误 的 信息 
语法 : open_file_cache_errors onloff; 


默认 :， open_file_cache_errors off; 


配置 块 : http、server、location 


此 配置 项 表示 是 否 在 文件 缓存 中 缓存 打开 文件 时 出 现 的 找 不 到 路 
径 、 没 有 权限 等 销 误 信息 。 


(7) 不 被 淘汰 的 最 小 访问 次 数 
语法 : open_file_cache_min_uses number; 
默认 :open_file_cache_min_uses 1; 
配置 块 : http、server、]location 


它 与 open_file_cache 中 的 inactive 参 数 配合 使 用 。 如 果 在 inactive 指 定 
的 时 间 段 内 ， 访 问 次 数 超过 了 open_file_cache_min_uses 指 定 的 最 小 次 
数 ， 那 么 将 不 会 被 淘汰 出 缓存 。 


(8) 检验 缓存 中 元 素 有 效 性 的 频率 
语法 : open_file_cache_valid time; 
默认 :open_file_cache_valid 60s; 
配置 块 : http、server、]location 


默认 为 每 60 秒 检查 一 次 缓存 中 的 元 素 是 否 仍 有 效 。 


2.4.8 对 客户 端 请 求 的 特殊 处 理 


下 面 介 绍 对 客户 问 请 求 的 特殊 处 理 的 配置 项 。 
(1) 忽略 不 合法 的 HTTP 头 部 

语法 : ignore_invalid_headers onloff; 

默认 :，ignore_invalid_headers on; 

配置 块 : http、server 


如 果 将 其 设置 为 off， 那 么 当 出 现 不 合法 的 HTTP 头 部 时 ，Nginx 会 
拒绝 服务 ， 并 直接 向 用 户 发 送 400 (Bad Request) 错误 。 如 果 将 其 设置 
为 on， 则 会 忽略 此 HTTP 头 部 。 


(2) HTTP 头 部 是 否 允 许 下 划 线 
语法 : underscores_in_headers on|off; 
默认 :underscores_in_headers off:; 
配置 块 : http 、server 
默认 为 of， 表 示 HTTP 头 部 的 名 称 中 不 允许 之 “” (下 划 线 ) 。 


(3) 对 If-Modified-Since 头 部 的 处 理 策略 


语法 : 证 modified_since[offlexact|before]; 
默认 : if_modified since exact; 
配置 块 : http、server、]location 


出 于 性 能 考虑 ，Web 浏 览 器 一 般 会 在 客户 端 本 地 缓存 一 些 文件 ， 并 
存储 当时 获取 的 时 间 。 这 样 ， 下 次 向 Web 服 务 器 获取 缓存 过 的 资源 时 ， 
残 可 以 用 If-Modified-Since 头 部 把 上 次 获取 的 时 间 撒 这 上 ， 而 
计 modified_since 将 根据 后 面 的 参数 决定 如 何 处 理 If-Modified-Since 头 


部 。 
相关 参数 说 明 如 下 。 


.off: 表示 忽略 用 户 请 求 中 的 If-Modified-Since 头 部 。 这 时 ， 如 果 获 
取 一 个 文件 ， 那 么 会 正常 地 返回 文件 内 容 。HTTP 啊 应 码 通 常 是 200。 


-exact: 将 If-Modified-Since 头 部 包含 的 时 间 与 将 要 返回 的 文件 上 次 
修改 的 时 间 做 精确 比较 ， 如 果 没 有 匹配 上 ， 则 返回 200 和 文件 的 实际 内 
容 ， 如 果 匹 配 上 ， 则 表示 浏览 器 缓存 的 文件 内 容 已 经 是 最 新 的 了 ， 没 
有 必要 再 返回 文件 从 而 浪费 时 间 与 带宽 了 ， 这 时 会 返回 304 Not 
Modified， 浏 览 器 收 到 后 会 直接 读 取 自己 的 本 地 缓存 。 


before: 是 比 exact 更 宽松 的 比较 。 只 要 文件 的 上 次 修改 时 间 等 于 
或 者 早 于 用 户 请 求 中 的 IE -Modified-Since 头 部 的 时 间 ， 就 会 向 客户 端 返 


回 304 Not Modified 。 


(4) 文件 未 找到 时 是 否 记 录 到 error 日 志 
语法 : log_not_found onloff; 
默认 :， log_not_ found on; 
配置 块 : http、server、location 


此 配置 项 表示 当 处 理 用 户 请 求 且 需要 访问 文件 时 ， 如 有 果 没 有 找到 
文件 ， 是 否 将 错误 日 志 记 录 到 errorlog 文 件 中 。 这 仅 用 于 定位 问题 。 


(5) merge_slashes 
语法 : merge_slashes onloff; 
默认 :， merge_slashes on; 
配置 块 : http、server、location 


此 配置 项 表示 是 否 合并 相 邻 的 “/”， 例 如 ，//test//a.txt， 在 配置 为 on 
时， 会 将 其 匹配 为 location/test/a.txt; 如果 配 置 为 of， 则 不 会 匹配 ，URI 
将 仍然 是 //test///a.txt 。 


(6) DNS 解析 地 址 


语法 : ， resolver address..: 
配置 块 : http、server、]location 
设置 DNS 名 字 解 析 服 务 恬 的 地 址 ， 例 如 : 


resolver 127.0.0.1 192.0.2.1; 


(7) DNS 解析 的 超时 时 间 
语法 : ”resolver_timeout time: 
默认 :， resolver timeout 30s; 
配置 块 : http 、server 、l]ocation 
此 配置 项 表示 DNS 解析 的 超时 时 间 。 
(8) 返回 错误 页 面 时 是 否 在 Server 中 注 明 Nginx 版 本 
语法 :， server_tokens onloff; 
默认 :， server_tokens on; 
配置 块 : http、server、location 


表示 处 理 请 求 出 错时 有 是 否 在 响应 的 Server 头 部 中 标明 Nginx 版 本 ， 


这 是 为 了 方便 定位 问题 。 


下 


2.4.9 ngx_http_core_module 模 块 提 供 的 变量 
在 记录 access_log 访 问 日 志文 件 时 ， 可 以 使 用 ngx_http_core_ module 
模块 处 理 请 求 时 所 产生 的 丰富 的 变量 ， 当 然 ， 这 些 变 量 还 可 以 用 于 其 
他 HTTP 模 块 。 例 如 ， 当 URI 中 的 某 个 参数 满足 设 定 的 条 件 时 ， 有 些 
HTTP 模 块 的 配置 项 可 以 使 用 类 似 $arg_PARAMETER 这 样 的 变量 。 又 
如 ， 寿 想 把 每 个 请 求 中 的 限 速 信 息 记 录 到 access 日 志文 件 中 ， 则 可 以 使 


用 $limit rate 变 量 


三 


表 2-1 列 出 了 ngx_http_core_module 模 块 提 供 的 这 些 变量 。 


表 2-1 ngx_http_core_module 模 块 提 供 的 变量 


参数 名 
$are PARAMETER 


$args 


$binary remote addr 
$body bytes_ sent 
$content length 
$content_ type 
$cookie COOKIE 
$document root 

Suri 


$document uri 


$request uri 


$host 


$hostname 


$http HEADER 
$sent http HEADER 


$is_args 


$limit rate 
$nginx_Yersion 
$query string 
Sremote addr 
Sremote_ port 
$remote user 
Srequest filename 
$request body 
$request body file 


$request completion 


$request method 
$scheme 


$server addr 


参数 名 
$server name 
$server_port 


$server_protocol 


意 义 

HTTP 请 求 中 茜 个 参数 的 值 ， 如 /index.html?size=100， 可 以 用 $arg_size 到 得 100 这 个 值 

HTTP 请 求 中 的 完整 参数 。 例 如 ， 在 请 求 /index.html?_w=120&_h=120 中 ，S$args 表示 
字符 串 _w=120&_h=120 

二 进 制 格式 的 客户 端 地 址 。 例 如 : \x0A\xE0B\x0E 

表示 在 向 客户 端 发 送 的 http 响应 中 ， 包 体 部 分 的 字 节 数 

表示 客户 端 请 求 尖 部 中 的 Content-Length 字段 

表示 客户 端 请 求 头 部 中 的 Content-Type 字段 

表示 在 客户 端 请 求 头 部 中 的 cookie 字段 

表示 当前 请 求 所 使 用 的 root 配置 项 的 值 

表示 当前 请 求 和 的 URI， 不 带 任何 参数 

与 $uri 含义 相同 

表示 客户 端 发 来 的 原始 请 求 URI， 带 完整 的 参数 。$uri 和 $document_uri 未 必 是 用 户 的 
原始 请 求 ， 在 内 部 重 定向 后 可 能 是 重 定向 后 的 URI， 而 $request_uri 永远 不 会 改变 ， 始 终 
是 客户 端的 原始 URI 

表示 客户 辫 请 求 头 部 中 的 Host 字段 。 如 果 Host 字段 不 存在 ， 则 以 实际 处 理 的 server 
(虚拟 主机 ) 和 名称 代 赫 -。 如 果 Host 字段 中 带 有 上 端口， 如 IP:PORT， 那 么 $host 是 去 掉 端 
口 的 ， 它 的 值 为 IP- $host 是 全 小 写 的 - 这 些 特性 与 htp_HEADER 中 的 http_host 不 同 ， 
http_host 只 是 “忠实 ”地 取出 Host 头 部 对 应 的 值 

表示 Nginx 所 在 机 器 的 名 称 。 与 gethostbyname 调用 返回 的 值 相同 

表示 当前 HTTP 请 求 中 相应 头 部 的 值 。 HEADER 名 称 全 小 写 。 例如， 用 $http_host 表 
示 请 求 中 Host 头 部 对 应 的 值 

表示 返回 客户 端的 HTTP 响 应 中 相应 头 部 的 值 。HEADER 名称 全 小 写 。 
$sent_http_content_type 表示 啊 应 中 Content-Type 头 部 对 应 的 值 

表示 请 求 中 的 URI 是 否 带 参数 ， 如 果 带 参数 ，S$is_args 值 为 ?， 如 果 不 带 参数 ， 则 是 空 
字符 捉 

表示 当前 连接 的 限 速 是 多 少 ，0 表示 无 限 速 

表示 当前 Nginx 的 版 本 号 ， 如 1.0.14 

请 求 URI 中 的 参数 ， 与 $args 相同 ， 然 而 $query_string 是 只 读 的 不 会 改变 

表示 客户 端的 地 址 

表示 客户 端 连接 使 用 的 端口 

表示 使 用 Auth Basic Module 时 定义 的 用 户 名 

表示 用 户 请 求 中 的 URI 经 过 root 或 alias 转换 后 的 文件 路 径 

表示 HTTP 请 求 中 的 包 体 ， 该 参数 只 在 proxy_pass 或 fastcgi_pass 中 有 意义 

表示 HTTP 请 求 中 的 包 体 存储 的 临时 文件 名 

当 请 求 已 经 全 部 完成 时 ， 其 值 为 “ ok”。 若 没有 完成 ,就 要 返回 客户 端 ， 则 其 值 为 空 
字符 串 ; 或 者 在 断 点 续 传 等 情况 下 使 用 HTTP range 访问 的 并 不 是 文件 的 最 后 一 块 、 那 么 
其 值 也 是 空 字符 串 

表示 HTTP 请 求 的 方法 名 ， 如 GET、PUT、POST 等 

表示 HTTP scheme， 如 在 请 求 https;//nginx.com/ 中 表示 https 


例如 ， 用 


表示 服务 器 地 址 
( 续 ) 
意 义 
表示 服务 器 名 称 
表示 服务 器 端口 


表示 服务 器 问 客户 端 发 送 响 应 的 协议 ， 如 HTTP/1.1 或 HITP/1.0 


2.5 用 HTTP proxy module 配 置 一 个 反 癌 代理 服务 


口 蝇 


反问 代理 (reverse proxy) 方式 是 指 用 代理 服务 器 来 接受 Internet 上 
的 连接 请 求 ， 然 后 将 请 求 转发 给 内 部 网 络 中 的 上 游 服 务 器 ， 并 将 从 上 
游 服 务 器 上 得 到 的 结果 返回 给 Internet 上 请 求 连接 的 客户 端 ， 此 时 代理 
服务 器 对 外 的 表现 丈 是 一 个 Web 服 务 硕 。 充 当 反 回 代 理 服 务 右 也 是 
Nginx 的 一 种 常见 用 法 ( 反 向 代理 服务 右 必 须 能 够 处 理 大 量 并 发 请 
求 ) ， 本 节 将 介绍 Nginx 作 为 HTTP 反 向 代理 服务 器 的 基本 用 法 。 


由 于 Nginx 具 有 “强悍 ”的 高 并 发 高 负载 能 力 ， 因 此 一 般 会 作为 前 端 
的 服务 紫 直 接 向 客户 并 提供 静 仿 文件 服务 。 但 也 有 一 些 复杂 、 多 变 的 
业务 不 适合 放 到 Nginx 服 务 器 上 ， 这 时 会 用 Apache、Tomcat 等 服务 器 来 
处 理 。 于 是 ，Nginx 通 音 会 被 配置 为 既是 静 信 Web 服务 瑚 也 是 反 辐 代理 
服务 器 (如 图 2-3 所 示 ) ， 不 适合 Nginx 处 理 的 请 求 就 会 直接 转发 到 上 游 
服务 占 中 处 理 。 


阁 悉 文 作 请 求 > 


炎 作 :内容 


Nginx Tomcat / Apache 等 
Web 浏览 之 静态 Web 服 务 咒 处 理 复杂 业务 的 动 


时 ER > 反 向 代理 服务 器 态 Web 服 务 器 


SN 
CWA 从 ~ 
扫 民 到 4 SR 


图 2-3 ”作为 静 仿 Web 服 务 句 与 反问 代理 服务 器 的 Nginx 


与 Squid 等 其 他 反 癌 代理 服务 器 相 比 ，Nginx 的 反 辣 代理 功能 有 自己 
的 特点 ， 如 图 2-4 所 示 。 


当 客 户 端 发 来 HTTP 请 求 时 ，Nginx 并 不 会 立刻 转发 到 上 游 服 务 
器 ， 而 是 先 把 用 户 的 请 求 (包括 HTTP 包 体 ) 完整 地 接收 到 Nginx 所 在 
服务 夯 的 硬盘 或 者 内 存 中 ， 然 后 再 癌 上 游 服 务 套 发 起 连接 ， 把 缓存 的 
客户 端 请 求 转发 到 上 游 服 务 器。 而 Squid 等 代理 服务 器 则 采用 一 边 接收 
客户 疹 请 求 ， 一 边 转发 到 上 游 服 务 闫 的 方式 。 


Nginx 的 这 种 工作 方式 有 什么 优 缺点 呢 ? 很 明显 ， 缺 点 是 延长 了 一 
个 请 求 的 处 理 时 间 ， 并 增加 了 用 于 缓存 请 求 内 容 的 内 存 和 磁盘 至 间 。 
而 优 护 则 古 降 低 了 上 游 服 务 右 的 人 负载， 尽量 把 压力 放 在 Nginx 服 务 右 
ee 


如 果 上 游 服 务 需 返回 内 
容 ， 则 不 会 先 完整 地 缓存 到 
Nginx 代 理 服务 器 再 向 客户 
端 转发 ， 而 是 边 接收 边 转 发 


We | 


用 户 发 来 的 请 求 将 会 完 
整地 缓存 到 Nginx 代 理 服 务 
器 ， 之 后 才 会 向 后 端 服务 
器 转发 ， 这 与 Squid 等 反 疝 
代理 服务 需 不 同 


Nginx 反问 
代理 服务 需 


缓存 请 求 的 HTTP 包 体 


Nginx 反 向 代理 服务 
费 可 以 根据 多 种 方案 
从 上 游 服务 器 的 集群 


中 选择 一 台 。 它 的 负 
载 均 衡 方案 包括 按 IP| ”一 一 
地 址 做 散 列 等 


上 上 游 服务 器 上 游 服 务 器 上 游 服务 器 
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图 2-4 ”Nginx 作 为 反 向 代理 服务 如 时 转发 请 求 的 流程 


Nginx 的 这 种 工作 方式 为 什么 会 降低 上 游 服 务 紫 的 负载 呢 ? 通 利 ， 
客户 端 与 代理 服务 器 之 间 的 网 络 环境 会 比较 复杂 ， 多 半 是 " 走 ” 公 网 ， 
网 速 平均 下 来 可 能 较 慢 ， 因 此 ， 一 个 请 求 可 能 要 持续 很 久 才能 完成 。 
而 代理 服务 器 与 上 游 服 务 器 之 间 一 般 是 " 走 ” 内 网 ， 或 者 有 专线 连接 ， 


传输 速度 较 快 。Squid 等 反 向 代理 服务 器 在 与 客户 端 建立 连接 且 还 没有 
开始 接收 HTTP 包 体 时 ， 就 已 经 向 上 游 服 务 器 建立 了 连接 。 例 如 ， 某 个 
请 求 要 上 传 一 个 1GB 的 文件 ， 那 么 每 次 Squid 在 收 到 一 个 TCP 分 包 (如 
2KB) 时 ， 就 会 即时 地 向 上 游 服 务 器 转发 。 在 接收 客户 端 完整 HITP 包 
体 的 漫长 过 程 中 ， 上 游 服 务 器 始终 要 维持 这 个 连接 ， 这 直接 对 上 游 服 
务 器 的 并 发 处 理 能 力 提 出 了 挑战 。 


Nginx 则 不 然 ， 它 在 接收 到 完整 的 客户 端 请 求 (如 1GB 的 文件 ) 
后 ， 才 会 与 上 游 服务 器 建立 连接 转发 请 求 ， 由 于 是 内 网 ， 所 以 这 个 转 
发 过 程 会 执行 得 很 快 。 这 样 ， 一 个 客户 闪 请 求 占用 上 游 服务 器 的 连接 
时 间 就 会 非常 短 ， 也 就 是 说 ，Nginx 的 这 种 反 向 代理 方案 主要 是 为 了 降 
低 上 游 服 务 旧 的 并 发 压力 。 


Nginx 将 上 游 服务 器 的 啊 应 转发 到 客户 端 有 许多 种 方法 ， 第 12 章 将 
介绍 其 中 音 见 的 两 种 方式 。 


2.5.1 ”负载 均衡 的 基本 配置 


作为 代理 服务 器 ， 一 般 都 需要 问 上 游 服务 器 的 集群 转发 请 求 。 这 
里 的 负载 均衡 是 指 选择 一 种 策略 ， 尽 量 把 请 求 平 均 地 分 布 到 每 一 台 上 
游 服 务 器 上 。 下面 介 绍 负载 均衡 的 配置 项 。 


(1) upstream 块 


语法 : upstream name{.…} 
配置 块 : http 


upstream 块 定义 了 一 个 上 游 服 务 右 的 集群 ， 便 于 反 回 代理 中 的 
proxy_pass 使 用 。 例 如 : 


upstream backend { 
server backend1.example .com; 
server backend2.example,.com; 
server backend3.example.com; 
} 
server { 
location / 
proxy_pass http://backend; 


(2) server 
语法 : ”server name[parameters]; 


配置 块 : upstream 


server 配 置 项 指定 了 一 台 上 游 服 务 絮 的 名 字 ， 这 个 名 字 可 以 是 域 
名 、 卫 地 址 端口 、UNIX 句 柄 等 ， 在 其 后 还 可 以 跟 下 列 参数 。 


weight=number: 设置 同 这 人 台 上 游 服 务 右 转发 的 权重 ， 默 认为 1。 


-max fails=number: 该 选项 与 fail_ timeout 配 合 使 用 ， 指 在 


fail_timeout 时 间 段 内 ， 如 果 癌 当前 的 上 游 服务 右 转 发 失败 次 数 超过 


number， 则 认为 在 当前 的 fail timeout 时 间 段 内 这 人 台 上 游 服 务 器 不 可 
用 。max_fails 默 认为 1， 如 果 设 置 为 0， 则 表示 不 检查 失败 次 数 。 


:fail_timeout=time: fail_timeout 表 示 该 时 间 段 内 转发 失败 多 少 次 后 
束 认 为 上 游 服务 器 暂时 不 可 用 ， 用 于 优化 反 辐 代理 功能 。 它 与 网上 游 
服务 器 建立 连接 的 超时 时 间 、 读 取 上 游 服务 器 的 啊 应 超时 时 间 等 完全 
无 关 。fail_timeout 默 认为 10 秒 。 


.down: 表示 所 在 的 上 游 服 务 器 永久 下 线 ， 只 在 使 用 ip_hash 配 置 项 
时 才 有 用 。 


-backup: 在 使 用 ip_hash 配 置 项 时 它 是 无 效 的 。 它 表示 所 在 的 上 游 
服务 器 只 是 备份 服务 器 ， 只 有 在 所 有 的 非 备 份 上 游 服 务 紫 部 失效 后 ， 
全 
Zs 


才 会 向 所 在 的 上 游 服 务 句 转发 请 求 。 
例如 : 
upstream backend { 
server backend1.example.com weight=5; 
server 127.0.0.1:8080 max_fails=3 fail timeout=30s,; 
server unix:/tmp/backend3; 
} 
(3) ip_hash 


语法 : ip_hash:; 


配置 块 : upstream 


在 有 些 场 景 下 ， 我 们 可 能 会 布 望 来 目 某 一 个 用 户 的 请 求 始终 落 到 
回 定 的 一 台 上 游 服 务 右 中 。 例 如 ,假设 上 游 服务 右 会 缓存 一 些 信 息 ， 
如 采 同 一 个 用 户 的 请 求 任 意 地 转发 到 集群 中 的 任 一 台 上 游 服务 器 中 ， 
那么 每 一 台 上 游 服 务 紫 部 有 可 能 会 缓存 同一 份 信息 ， 这 有 既 会 造成 资源 
的 浪费 ， 也 会 难以 有 效 地 管理 缓存 信息 。ip_hash 谍 古 用 以 解决 上 述 问 
题 的 ， 它 首 先 根据 客户 端的 IP 地 址 计算 出 一 个 key， 将 key 按 照 upstream 
集群 里 的 上 游 服 务 右 数量 进行 取 模 ， 然 后 以 取 模 后 的 结 来 把 请 来 转发 
到 相应 的 上 游 服 务 絮 中。 这 样 束 确保 了 同一 个 客户 端的 请 求 只 会 转发 
到 指定 的 上 游 服 务 右 中 。 


ip_hash 与 weight (权重 ) 配置 不 可 同时 使 用 。 如 果 upstream 和 集群 中 
有 一 台 上 游 服 务 妖 暂时 不 可 用 ， 不 能 直接 删除 该 配置 ， 而 是 要 down 参 
数 标 识 ， 确 保 转 发 策略 的 一 贯 性 。 例 如 : 


upstream backend { 
ip_hash; 
server backend1.example.com; 
server backend2.example.com; 
server backend3.example.com down; 
server backend4.example.com; 


(4) 记录 日 志 时 支持 的 变量 


如 果 需 要 将 负载 均衡 时 的 一 些 信息 记录 到 access log 日 志 中 ， 那 么 
在 定义 日 志 格 式 时 可 以 使 用 负载 均衡 功能 提供 的 变量 ， 见 表 2-2。 


表 2-2 ”访问 上 游 服务 郁 时 可 以 使 用 的 变量 


变量 名 意 义 


S$upstream addr 处 理 请 求 的 上 游 服务 器 地 址 


$upstream cache status 表示 是 否 命 中 缓存 ， 取 值 范 围 : MISS、EXPIRED 、UPDATING、STALE 、HIT 
S$upstream status 上 游 服 务 器 返回 的 响应 中 的 HTTP 响应 人 码 
S$upstream response time 上 游 服 务 器 的 响应 时 间 ， 精 度 到 毫秒 


S$upstream http_ SHEADER HTTP 的 头 部 ， 如 upstream_http_host 


例如 ， 可 以 在 定义 access_log 访 问 日 志 格 式 时 使 用 表 2-2 中 的 变量 。 


log format timing '$remote addr - $remote user [$time local] $request ' 
'upstream response time $upstream response time ' 
"msec $msec request_ time $request time'; 

log_format up_head '$remote addr - $remote user [$time local] $request ' 
"Upstream_http_content_type $upstream http_content_type'; 


2.5.2 ” 反 癌 代理 的 基本 配置 


下 面 介绍 反 疝 代理 的 基本 配置 项 。 
(1) proxy_pass 

语法 : proxy_pass URL; 

配置 块 : location、if 


此 配置 项 将 当前 请 求 反 回 代 理 到 URL 参 数 指定 的 服务 种 上 ，URL 
可 以 是 主机 和 名 或 下 地 址 加 端口 的 形式 ， 例 如 : 


proxy_pass http://localhost:8000/uri/ 


了 


也 可 以 是 UNIX 句 柄 : 


proxy_pass http://unix:/path/to/backend.socket:/uri/ 


还 可 以 如 上 市 负载 均衡 中 所 示 ， 直 接 使 用 upstream 块 ， 例 如 : 


upstream backend { 


} 
server { 
location / { 
proxy_pass http://backend 


用 户 可 以 把 HTTP 转 换 成 更 安全 的 HTTPS， 例 如 : 


proxy_pass https://192.168.0.1 


默认 情况 下 反 向 代理 是 不 会 转发 请 求 中 的 Host 头 部 的 。 如 果 需 要 
转发 ， 那 么 必须 加 上 配置 : 


proxy_set_header Host $host; 


(2) proxy_method 


语法 : ”proxy_method method; 


配置 块 : http、server、location 
此 配置 项 表示 转发 时 的 协议 方法 名 。 例 如 设置 为 : 


proxy_method POST ， 


那么 客户 端 发 来 的 GET 请 求 在 转发 时 方法 名 也 会 改 为 POST 。 
(3) proxy_hide_header 
语法 : proxy_hide_header the_header; 
配置 块 : http、server、]location 


Nginx 会 将 上 游 服 务 絮 的 啊 应 转发 给 客户 端 ， 但 默认 不 会 转发 以 下 
HTTP 头 部 字段 : Date、Server、X-Pad 和 X-Accel-*。 使 用 
proxy_hide_header 后 可 以 任意 地 指定 哪些 HTTP 头 部 字段 不 能 被 转发 。 
例如 : 


proxy_hide_header Cache-Control; 
proxy_hide_header MicrosoftofficewebServer ; 


(4) proxy_pass_header 
语法 : proxy_pass_header the_header; 


配置 块 : http、server、]location 


与 proxy_hide_header 功 能 相反 ，proxy_pass_header 会 将 原来 禁止 转 
发 的 header 设 置 为 允许 转发 。 例 如 : 


proxy_pass_header Xx-Accel-Redirect,; 


(5) proxy_pass_request body 

语法 : ”proxy_pass_request_body on|off; 

默认 :，proxy_pass_request_body on; 

配置 块 : http、server、]location 

作用 为 确定 是 否 同上 游 服 务 絮 发 送 HTTP 包 体 部 分 。 
(6) proxy_pass_request headers 

语法 : proxy_pass_request_headers on|off; 

默认 :，proxy_pass_request_headers on; 


配置 块 : http、server、location 


作用 为 确定 是 否 转发 HITP 头 部 。 
(7) proxy_redirect 


语法 : proxy_redirect[defaultlofflredirect replacement]; 


默认 :，proxy_redirect default; 


配置 块 : http、server、]location 


当 上 游 服 务 器 返回 的 响应 是 重 定 癌 或 刷新 请 求 (如 HTTP 响 应 码 是 
301 或 者 302) 时 ，proxy_redirect 可 以 重 设 HTTP 头 部 的 location 或 refresh 
字段 。 例 如 ， 如 果 上 游 服务 器 发 出 的 响应 是 302 重 定向 请 求 ，location 字 
段 的 URI 是 http://localhost:8000/two/some/uri/ ， 那 么 在 下 面 的 配置 情况 
下 ， 实 际 转 发 给 客户 端的 location 是 http://frontend/one/some/uri/ 。 


proxy_redirect http://localhost:8000/two/ 


http://frontend/one/; 


这 里 还 可 以 使 用 ngx-http-core-module 提 供 的 变量 来 设置 新 的 


location 字 7 段 。 例 如: 


proxy_redirect http://localhost:8000/ 


http://$host:$server_port/; 


也 可 以 省 略 replacement 参 数 中 的 主机 名 部 分 ， 这 时 会 用 虚拟 主机 名 
称 来 填充 。 例 如 : 


proxy_redirect http://localhost:8000/two//one/ 


人 


使 用 off 参 数 时 ， 将 使 location 或 者 refresh 字 段 维持 不 变 。 例 如 : 


proxy_redirect off; 


使 用 默认 的 default 参 数 时 ， 会 按照 proxy_pass 配 置 项 和 所 属 的 
location 配 置 项 重组 发 往 客 户 端的 location 头 部 。 例 如 ， 下 面 两 种 配置 效 
果 是 一 样 的 : 


location /one/ { 
proxy_pass http://upstream:port/two/ 


. 
proxy_redirect default; 
location /one/ { 


proxy_pass http://upstream:port/two/ 


了 
proxy_redirect http://upstream:port/two//one/ 


(8) proxy_next_ upstream 


语法 ; 
proxy_next_upstreaml[errorltimeoutlinvalid_headerlhttp_500|http_502|http_5 


03|http_504|http_404|off]; 
默认 :，proxy_next_upstream error timeout; 


配置 块 : http、server、location 


此 配置 项 表示 当 疝 一 台 上 游 服 务 占 转发 请 求 出 现 错 误 时 ， 继 续 换 
一 人 台 上 游 服 务 紫 人 处理 这 个 请 求 。 前 面 已 经 说 过 ， 上 游 服务 右 一 旦 开始 
发 送 应 答 ，Nginx 反 癌 代 理 服 务 器 会 立刻 把 应 答 包 转 发 给 客户 端 。 因 
此 ， 一旦 Nginx 开 始 阿 客户 端 发 送 啊 应 包 ， 之 后 的 过 程 中 知 出 现 错误 也 
征 不 允许 换 下 一 台 上 游 服 务 央 继续 处 理 的 。 这 很 好 理解 ， 这 样 才 可 以 
更 好 地 保证 客户 闻 只 收 到 来 目 一 个 上 游 服 务 右 的 应 答 。 
proxy_next_upstream 的 参数 用 来 说 明 在 哪些 情况 下 会 继续 选择 下 一 台 上 
游 服 务 右 转发 请 求 。 


-error: 当 癌 上游 服务 万 发 起 连接 、 发 送 请 求 、 读 取 啊 应 时 出 错 。 


:timeout: 发 送 请 求 或 读 取 啊 应 时 发 生 超时 。 
invalid_header: 上 游 服务 器 发 送 的 啊 应 古 不 合法 的 。 
:http_500: 上 游 服 务 需 返回 的 HTTP 啊 应 码 是 500 。 
http_502: 上 游 服 务 需 返回 的 HTTP 啊 应 码 是 502 。 
http_503: 上 游 服 务 需 返回 的 HTTP 啊 应 码 是 503 。 
http_504: 上 游 服 务 需 返回 的 HTTP 啊 应 码 是 504 。 


http_404: 上 游 服 务 需 返回 的 HTTP 啊 应 码 是 404 。 


:off: 关闭 proxy_next_upstream 功 能 一 出 错 丈 选 择 另 一 侣 上游 服务 
釉 再 次 转发 。 


Nginx 的 反 回 代理 模块 还 提供 了 很 多 种 配置 ， 如 设置 连接 的 超时 时 
间 、 临 时 文件 如 何 存 储 ， 以 及 最 重要 的 如 何 缓存 上 游 服 务 妖 啊 应 等 功 
能 。 这 些 配置 可 以 通过 阅读 ngx_http_proxy_module 模 块 的 说 明了 解 ， 
只 有 深入 地 理解 ， 才 能 实现 一 个 高 性 能 的 反 向 代理 服务 器 。 本 万 只 是 
介绍 反 向 代理 服务 器 的 基本 功能 ， 在 第 12 革 中 我 们 将 会 深入 地 探索 
upstream 机 制 ， 到 那 时 ， 读 者 也 许 会 发 现 ngx_http_proxy_module 模 块 只 
是 使 用 upstream 机 制 实现 了 反 辐 代理 功能 而 已 。 


2.6 小结 


Nginx 由 少量 的 核心 框架 代码 和 许多 模块 组 成 ， 每 个 模块 部 有 它 独 
等 的 功能 。 因 此 ， 读 者 可 以 通过 查看 每 个 模块 实现 了 什么 功能 ， 来 了 
解 Nginx 可 以 帮 我 们 做 些 什么 。 


Nginx 的 Wiki 网 站 (http://wiki.nginx.org/Modules ) 上 列 出 了 官方 
提供 的 所 有 模块 及 配置 项 ， 仔 细 观 察 就 会 发 现 ， 这 些 配置 项 的 语法 与 
本 半 的 内 容 都 是 很 相近 的 ， 读 者 只 需要 弄 清 楚 模 块 说 明 中 每 个 配置 项 
的 意义 即 可 。 另 外 ， 网 页 http:/wiki.nginx.org/3rdPartyModules 中 列 出 
了 Wiki 上 已 知 的 几 十 个 第 三 方 模块 ， 同 时 读者 还 可 以 从 搜索 引擎 上 搜 
索 到 更 多 的 第 三 方 模块 。 了 解 每 个 模块 的 配置 项 用 法 ， 并 在 Nginx 中 使 
用 这 些 模块 ， 可 以 让 Nginx 做 到 更 多 。 


随 着 对 本 书 的 学 习 ， 读 者 会 对 Nginx 模 块 的 设计 思路 有 深入 的 了 
解 ， 也 会 渐渐 熟悉 如 何 编写 一 个 模块 。 如 果菜 个 模块 的 实现 与 你 的 想 
法 有 出 入 ， 可 以 更 改 这 个 模块 的 源码 ， 实 现 你 期 望 的 业务 功能 。 如 采 
所 有 的 模块 都 没有 你 想 要 的 功能 ， 不 妨 目 己 重 写 一 个 定制 的 模块 ， 也 
可 以 申请 发 布 到 Nginx 网 站 上 供 大 家 分 享 。 


第 二 部 分 ”如何 编写 HTTP 模 块 


开发 一 个 简单 的 HITP 模 块 


章 ”配置 、error 日 志和 请 求 上 下 文 


章 ”访问 第 三 方 服 务 


开发 一 个 简单 的 HTTP 过 滤 模 块 


Nginx 提 供 的 高 级 数据 结构 


第 3 草 ”开发 一 个 简单 的 HTTP 模 块 


当 通 过 开发 HTTP 模 块 来 实现 产品 功能 时 ， 是 可 以 完全 至 用 Nginx 
的 优秀 设计 所 融 来 的 、 与 官方 模块 相同 的 高 并 发 特性 的 。 不 过 ， 如 何 
开发 一 个 充满 异步 调用 、 无 阻塞 的 HTTP 模 块 呢 ? 首先 ， 需 要 把 程序 航 
入 到 Nginx 中 ， 也 就 是 说 ， 最 终 编 译 出 的 二 进 制 程序 Nginx 要 包含 我 们 
的 代码 ( 见 3.3 节 ) ; 其 次 ， 这 个 全 新 的 HITP 模 块 要 能 介入 到 HITP 请 
求 的 处 理 流程 中 〈 具 体 参 见 3.1 节 、3.4 节 、3.5 节 ) 。 满 足 上 述 两 个 前 
提 后 ， 我 们 的 模块 才能 开始 处 理 HTTP 请 求 ， 但 在 开始 处 理 请 求 前 还 需 
要 先 了 解 一 些 Nginx 框 架 定义 的 数据 结构 ( 见 3.2 广 )y ， 这 是 后 面 必 须 
要 用 到 的 ， 正 式 处 理 请 求 时 ， 还 要 可 以 获得 Nginx 框 架 接 收 、 解 析 后 的 
用 户 请 求 信息 〈 见 3.6 节 ) ; 业务 执行 完毕 后 ， 则 要 考虑 发 送 响应 给 用 
户 〈 见 3.7 放 ) ， 包 括 将 磁 副 中 的 文件 以 HTTP 包 体 的 形式 发 送 给 用 户 

( 见 3.8 节 ) 。 


本 章 最 后 会 讨论 如 何 用 C++ 语言 来 编写 HTTP 模 块 ， 这 虽然 不 是 
Nginx 官 方 倡导 的 方式 ， 但 C++ 同 前 兼容 C 语 言 ， 使 用 C++ 语 言 开发 的 
模块 还 是 可 以 很 容易 地 藤 入 到 Nginx 中 。 本 章 不 会 深入 探讨 HTTP 模块 
与 Nginx 的 各 个 核心 模块 是 如 何 配合 工作 的 ， 而 且 这 部 分 提 到 的 每 个 接 
口 将 只 涉及 用 法 而 不 涉及 实现 原理 ， 在 第 3 部 分 我 们 才 会 进一步 阐述 本 
章 提 到 的 许多 接口 是 如 何 实现 异步 访问 的 。 


3.1 如 何 调 用 HTTP 模 块 


在 开发 HTTP 模 块 前 ， 首 先 需 要 了 解 典 型 的 HTTP 模 块 是 如 何 介入 
Nginx 处 理 用 户 请 求 流程 的 。 图 3-1 是 一 个 简化 的 时 序 图 ， 这 里 省 略 了 许 
多 异步 调用 ， 忽 略 了 多 个 不 同 的 HTTP 处 理 阶段 ， 仅 标识 了 在 一 个 典型 
请 求 的 处 理 过 程 中 主要 模块 被 调用 的 流程 ， 以 此 帮助 读者 理解 HTTP 模 
块 如 何 处 理 用 户 请 求 。 完 整 的 流程 将 在 第 11 章 中 详细 介绍 。 
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图 3-1 Nginx HTTP 模 块 调用 的 简化 流程 


从 图 3-1 中 看 到 ，worker 进 程 会 在 一 个 for 循 环 语句 里 反复 调用 事件 
模块 检测 网 络 事 件 。 当 事件 模块 检测 到 某 个 客户 端 发 起 的 TCP 请 求 时 
(接收 到 SYN 包 ) ， 将 会 为 它 建 立 TCP 连 接 ， 成 功 建立 连接 后 根据 
nginx.conf 文 件 中 的 配置 会 交 由 HTTP 框 架 处 理 。HTTP 框 架 会 试图 接收 
完整 的 HTTP 头 部 ， 并 在 接收 到 完整 的 HTTP 头 部 后 将 请 求 分 发 到 具体 


的 HITP 模 块 中 处 理 。 这 种 分 发 策略 是 多 样 化 的 ， 其 中 最 常见 的 是 根据 
请 求 的 URI 和 nginx.conf 里 location 配 置 项 的 匹配 度 来 决定 如 何 分 发 (本 
章 的 例子 正 是 应 用 这 种 分 发 策略 ， 在 第 10 章 中 会 介绍 其 他 分 发 策 

略 ) 。HTTP 模 块 在 处 理 请 求 的 结束 时 ， 大 多 会 向 客户 端 发 送 响 应 ， 此 
时 会 自动 地 依次 调用 所 有 的 HTTP 过 滤 模 块 ， 每 个 过 滤 模 块 可 以 根据 配 
置 文 件 决定 自己 的 行为 。 例 如 ，gzip 过 滤 模 块根 据 配置 文件 中 的 gzip 
onloff 来 决定 是 否 压缩 响应 。HTTP 人 处理 模块 在 返回 时 会 将 控制 权 交 还 给 
HTTP 框 架 ， 如 果 在 返回 前 设置 了 subrequest， 那 么 HTTP 框 架 还 会 继续 
异步 地 调用 适合 的 HTTP 模 块 处 理子 请 求 。 


开发 HTTP 模 块 时 ， 首 先 要 注意 的 就 是 HTTP 框 架 到 具体 的 HTTP 模 
块 间 数 据 流 的 传递 ， 以 及 开发 的 HTTP 模块 如 何 与 诸多 的 过 滤 模 块 协同 
工作 (第 10 章 、 第 11 章 会 详细 介绍 HTTP 框 架 ) 。 下 面 正式 进入 HTTP 
模块 的 开发 环节 。 


3.2 ”准备 工作 


Nginx 模 块 需要 使 用 C 〈 或 者 C++) 语言 编写 代码 来 实现 ， 每 个 模 
块 都 要 有 上 自己 的 名 字 。 按 照 Nginx 约 定 俗 成 的 命名 规则 ， 我 们 把 第 一 个 
HTTP 模 块 命 名 为 ngx_http_mytest_ module。 由 于 第 一 个 模块 非常 简单 ， 
一 个 C 源 文件 就 可 以 完成 ， 所 以 这 里 按照 官方 惯例 ， 将 唯一 的 源 代码 文 
件 命名 为 ngx_http_mytest_module.c 。 


实际 上 ， 我 们 还 需要 定义 一 个 名 称 ， 以 便 在 编译 前 的 configure 命 令 
执行 时 显示 是 否 执行 成 功 〈《 即 configure 脚 本 执行 时 的 ngx_addon_name 
变量 ) 。 为 方便 理解 ， 仍 然 使 用 同一 个 模块 名 来 表示 ， 如 


ngx_http_mytest_module ° 


为 了 让 HTTP 模 块 正 常 工作 ， 首 先 需 要 把 它 编译 进 Nginx (3.3 市 会 
探讨 编译 新 增 模块 的 两 种 方式 ) 。 其 次 需要 设 定 模块 如 何在 运行 中 生 
效 ， 比 如 在 图 3-1 描 述 的 典型 方式 中 ， 配 置 文件 中 的 location 块 决定 了 匹 
配 某 种 URI 的 请 求 将 会 由 相应 的 HTTP 模块 处 理 ， 因 此 ， 运 行 时 HTTP 框 
架 会 在 接收 完毕 HTTP 请 求 的 头 部 后 ， 将 请 求 的 URI 与 配置 文件 中 的 所 
有 1location 进 行 匹 配 〈 事 实 上 会 优先 匹配 虚拟 主机 ， 第 11 章 会 详细 说 明 
该 流程 ，， 匹 配 后 再 根据 location{} 内 的 配置 项 选择 HTTP 模 块 来 调用 。 
这 是 一 种 最 典型 的 HTTP 模 块 调用 方式 。3.4 廊 将 解释 HTTP 模 块 定义 骨 


入 方式 时 用 到 的 数据 结构 ，3.5 太 将 定义 我 们 的 第 一 个 HTTP 模 块 ，3.6 
斑 中 介绍 如 何 使 用 上 述 模 块 调用 方式 来 处 理 请 求 。 


既然 有 典型 的 调用 方式 ， 目 然 也 有 非典 型 的 调用 方式 ， 比 如 
ngx_http_access_module 模 块 ， 它 是 根据 耻 地 址 决定 某 个 客户 端 是 否 可 
以 访问 服务 的 ， 因 此 ， 这 个 模块 需要 在 NGX_HTTP_ACCESS_PHASE 
阶段 〈 在 第 10 章 中 会 详 述 HTTP 框 架 定 义 的 11 个 阶段 ) 生效 ， 它 会 比 本 
章 介绍 的 mytest 模 块 更 早 地 介入 请 求 的 处 理 中 ， 同 时 它 的 流程 与 图 3-1 
中 的 不 同 ， 它 可 以 对 所 有 请 求 产生 作用 。 也 就 是 说 ， 任 何 HITP 请 求 都 
会 调用 ngx_http_access_module 模 块 处 理 ， 只 是 该 模块 会 根据 它 感 兴趣 
的 配置 项 及 所 在 的 配置 块 来 决定 行为 方式 ， 这 与 mytest 模 块 不 同 ， 在 
mytest 模 块 中 ， 只 有 在 配置 了 location/uri{mytest;} 后 ，HTTP 框 染 才 会 在 
某 个 请 求 匹配 了 muri 后 调用 它 处 理 请 求 。 如 果 某 个 匹配 了 URI 请 求 的 
location 中 没有 配置 mytest 配 置 项 ，mytest 模 块 依然 是 不 会 被 调用 的 。 


为 了 做 到 跨 平 台 ，Nginx 定 义 、 封 狐 了 一 些 基 本 的 数据 结构 。 由 于 
Nginx 对 内 存 分 配 比较 “ 音 冀 ”只 有 保证 低 内 存 消耗 ， 才 可 能 实现 十 万 
甚至 百 万 级 别 的 同时 并 发 连接 数 ) ， 所 以 这 些 Nginx 数 据 结构 天 生 都 是 
尽 可 能 少 占用 内 存 。 下 面 介绍 本 章 中 将 要 用 到 的 Nginx 定 义 的 几 个 基本 
数据 结构 和 方法 ， 在 第 7 草 还 会 介绍 一 些 复 杂 的 容器 ， 读 者 可 以 从 中 体 
会 到 如 何 才 能 有 效 地 利用 内 存 。 


3.2.1 整 型 的 封装 


Nginx 使 用 ngx_int_t 封 装 有 人 符号 整 型 ， 使 用 ngx_uint_t 封 装 无 符号 整 
型 。Nginx 各 模块 的 变量 定义 都 是 如 此 使 用 的 ， 建 议 读 者 沿用 Nginx 的 
习惯 ， 以 此 替代 int 和 unsinged int。 


在 Linux 平 台 下 ，Nginx 对 ngx_int_t 和 ngx_uint t 的 定义 如 下 : 


typedef intptr_t ngx_int_t; 
typedef uintptr_t ngx_uint_t; 


3.2.2 ”ngx_str_t 数 据 结构 


在 Nginx 的 领域 中 ，ngx_str_ {t 结 构 承 是 字符 串 。ngx_str_{t 的 定义 如 


下 : 
typedef struct { 
size_t len; 
u_char *data; 
} ngx_str_t; 


ngx_str_t 只 有 两 个 成 员 ， 其 中 data 指 针 指 向 字符 串 起 始 地 址 ，len 表 
示 字 符 串 的 有 效 长 度 。 注 意 ，ngx_str_t 的 data 成 员 指 向 的 并 不 是 普通 的 
字符 串 ， 因 为 这 段 字符 串 未 必 会 以 \0' 作 为 结尾 ， 所 以 使 用 时 必须 根据 
长 度 len 来 使 用 data 成 员 。 例 如 ， 在 3.7.2 节 中 ， 我 们 会 看 到 r- 


>method_name 束 是 一 个 ngx_str_t 类 型 的 变量 ， 比 较 method_name 时 必须 


如 下 这 样 使 用 : 


If (© == ngx_strncmp( 
r->method_name.data, 
TT PUT mm 7 
r->method_name.1len) 


这 里 ，ngx_strncmp 其 实 就 是 stncmp 函 数 ， 为 了 跨 平 台 Nginx 习 惯 
性 地 对 其 进行 了 名 称 上 的 封装 ， 下 面 看 一 下 它 的 定义 : 


#define ngx_strncmp(s1, s2, n) strncmp((const char *) S1，(const char *) s2, n) 


任何 试图 将 ngx_str_t 的 data 成 员 当 做 字符 串 来 使 用 的 情况 ， 都 可 能 
导致 内 存 越界 ! Nginx 使 用 ngx_str_t 可 以 有 效 地 降低 内 存 使 用 量 。 例 
如 ， 用 户 请 求 “<GET/testa=1 http/1.1\m\n” 存 储 到 内 存 地 址 0x1d0b0110 上 ， 
这 时 只 需要 把 r->method_name 设 置 为 {len=3,data=0x1d0b0110} 就 可 以 表 

方法 名 “GET”， 而 不 需要 单独 为 method_name 再 分 配 内 存 见 余 的 存储 


直 
字符 串 。 
3.2.3 ngx_list_t 数 据 结 构 


ngx_list_t 是 Nginx 封 狂 的 链表 容 促 ， 它 在 Nginx 中 使 用 得 很 频 粽 ， 
例如 HITP 的 头 部 丈 是 用 ngx_list t 来 存储 的 。 当 然 ，C 语 言 封装 的 链表 


没有 C++ 或 Java 等 面向 对 象 语言 那么 容易 理解 。 先 看 一 下 ngx_list_t 相 关 
成 员 的 定义 : 


typedef struct ngx_list part_s ngx_list part_t; 
struct ngx_list part_s { 

void *elts,; 

ngx_uint_t nelts,; 


ngx_list part_t *next; 


}; 

typedef struct { 
ngx_list part_t *last; 
ngx_list_part_t part; 
size_t size,; 
ngx_uint_t nalloc; 
ngx_pool_t *pool; 

} ngx_list_t,; 


ngx_list_t 描 述 整 个 链表 ， 而 ngx_list_part_t 只 描述 链表 的 一 个 元 
素 。 这 里 要 注意 的 是 ，ngx_list_t 不 是 一 个 单纯 的 链表 ， 为 了 便于 理 
解 ， 我 们 姑且 称 它 为 存储 数组 的 链表 ， 什 么 意思 呢 ? 抽象 地 说 ， 就 是 
每 个 链表 元 素 ngx_list_part_t 义 是 一 个 数组 ， 拥 有 连续 的 内 存 ， 它 既 依 
赖 于 ngx_list_t 里 的 size 和 nalloc 来 表示 数组 的 容量 ， 同 时 又 依靠 每 个 
ngx_list_part_t 成 员 中 的 nelts 来 表示 数组 当前 已 使 用 了 多 少 容量 。 
此 ，ngx_list_t 是 一 个 链表 容 右 ， 而 链表 中 的 元 素 义 是 一 个 数组 。 事 实 
上 上 ，ngx_list_part_t 数 组 中 的 元 寻 才 是 用 户 想 要 和 存储 的 东西 ，ngx_list_t 
链表 能 够 容纳 的 元 素数 量 由 ngx_list_part_t 数 组 元 素 的 个 数 与 每 个 数组 
所 能 容纳 的 元 素 相 乘 得 到 。 


这 样 设计 有 什么 好 处 呢 ? 


-链表 中 存储 的 元 素 是 灵活 的 ， 它 可 以 是 任何 一 种 数据 结构 。 


链表 元 素 需 要 占用 的 内 存 由 ngx_list_t 管 理 ， 它 已 经 通过 数组 分 配 
WP 


小 块 的 内 存 使 用 链表 访问 效率 是 低下 的 ， 使 用 数组 通过 偏 移 量 来 
直接 访问 内 存 则 要 高 效 得 


下 面 详 述 每 个 成 员 的 意义 
(1) ngx_ list_t 
part: 链表 的 首 个 数组 元 素 。 
last:， 指 同 链 表 的 最 后 一 个 数组 元 素 。 


size: 前 面 讲 过 ， 链 表 中 的 每 个 ngx_list_part_t 元 素 都 是 一 个 数组 。 
因为 数组 存储 的 是 某 种 类 型 的 数据 结构 ， 且 ngx_list_t 是 非常 灵活 的 数 
据 结构 ， 所 以 它 不 会 限制 存储 什么 样 的 数据 ， 只 是 通过 size 限 制 每 一 个 
数组 元 素 的 占用 的 空间 大 小 ， 也 就 是 用 户 要 存储 的 一 个 数据 所 占用 的 
字 节 数 必须 小 于 或 等 于 size。 


-nalloc: 链表 的 数组 元 系 一 旦 分 配 后 是 不 可 更 改 的 。nalloc 表 示 每 
个 ngx_list_part_t 数 组 的 容量 ， 即 最 多 可 存储 多 少 个 数据 。 


.pool: 链表 中 管理 内 存 分 配 的 内 存 池 对 象 。 用 户 要 存放 的 数据 占 
用 的 内 存 都 是 由 pool 分 配 的 ， 下 文中 会 详细 介 


(2) ngx_jlist_part_f 


-elts: 指 辐 数组 的 起 始 地 址 。 


nelts: 表示 数组 中 已 经 使 用 了 多 少 个 元 素 。 当 然 ，nelts 必 须 小 于 


ngx_jist_t 结 构 体 中 的 nalloc。 
next: 下 一 个 链表 元 素 ngx_list_part_t 的 地 址 。 


事实 上 ，ngx_list_t 中 的 所 有 数据 都 是 由 ngx_pool_t 类 型 的 pool 内 存 
池 分 配 的 ， 它 们 通常 都 是 连续 的 内 存 (在 由 一 个 pool 内 存 池 分 配 的 情况 
下 ) 。 下 面 以 图 3-2 为 例 来 看 一 下 ngx_list_t 的 内 存 分 布 情况 。 


ngx_list_1 


Nex_list_part_t (3) 


Negx_list_part_t (1) 


Ngx_list_part_t (2) 


elts nelts 


elts nelts next 


size fnalloc 
UE 


J 


本 段 内 存 存储 本 段 内 存 存储 本 段 内 存 存 储 本 段 内 存 存储 
nex_list_1 nex _list ngx _list ngx _list 
结构 par t(1) part_t (2) part t (3) 
结构 结构 结构 


图 3-2 ”ngx_list_t 的 内 存 分 布 


图 3-2 中 是 由 3 个 ngx_list_part_t 数 组 元 素 组 成 的 ngx_list_t 链 表 可 能 
拥有 的 一 种 内 存 分 布 结构 ， 读 者 可 以 从 这 种 较为 间 见 的 内 存 分 布 中 看 
到 ngx_list_t 链 表 的 用 法 。 这 里 ，poo] 内 存 池 为 其 分 配 了 连续 的 内 存 ， 最 
前 端 内 存 存储 的 是 ngx_list_t 结 构 中 的 成 员 ， 紧 接着 是 第 一 个 
ngx_list_part_t 结 构 占 用 的 内 存 ， 然 后 是 ngx_list_part_t 结 构 指 同 的 数 
组 ， 它 们 一 共 占 用 size*nalloc 字 广 ， 表 示 数 组 中 拥有 nalloc 个 大 小 为 size 
的 元 素 。 其 后 面 是 第 2 个 ngx_list_part_t 结 构 以 及 它 所 指 回 的 数组 ， 依 此 
类 推 。 


对 于 链表 ，Nginx 提 供 的 接口 包括 : ngx_list_create 接 口 用 于 创建 新 
的 链表 ，ngx_list_init 接 口 用 于 初始 化 一 个 已 有 的 链表 ，ngx_list_push 接 
口 用 于 添加 新 的 元 素 ， 如 下 所 示 : 


ngx_list_t *ngx_list_create(ngx_pool_t *pool, ngx_uint_t n，Size_t Size) 
static ngx_inline ngx_int_t 

ngx_list_ init(ngx_list _t *list, ngx_pool t *pool, ngx_uint_t n, size _t size); 
void *ngx_list_push(ngx_list t *]ist); 


调用 ngx_list_create 创 建 元 素 时 ，pool 参 数 是 内 存 池 对 象 (参见 
3.7.2 节 ) ，size 是 每 个 元 素 的 大 小 ，n 是 每 个 链表 数组 可 容纳 元 素 的 个 
数 (相当 于 ngx_list_t 结 构 中 的 nalloc 成 员 ) 。ngx_list_create 返 回 新 创建 
的 链表 地 址 ， 如 果 创 建 失败 ， 则 返回 NULL 空 指针 。ngx_list_create 被 调 
用 后 至 少 会 创建 一 个 数组 〈 不 会 创建 空 链表 ) ， 其 中 包含 n 个 大 小 为 
size 字 世 的 连续 内 存 块 ， 也 就 是 ngx_list_t 结 构 中 的 part 成 员 。 


下 面 看 一 个 简单 的 例子 ， 我 们 首先 建立 一 个 链表 ， 它 存储 的 元 素 
征 ngx_str t， 其 中 每 个 链表 数组 中 存储 4 个 元 素 ， 代 码 如 下 所 示 : 


ngx_list_t* testlist = ngx_list create(r->pool, 4,sizeof(ngx_str_t)); 
If (testlist == NULL) { 

return NGX_ERROR; 
} 


ngx_list_init 的 使 用 方法 与 ngx_list_create 非 常 类 似 ， 需 要 注意 的 
是 ， 这 时 链表 数据 结构 已 经 创建 好 了 ， 若 ngx_list_init 返 回 NGX_OK， 
则 表示 初始 化 成 功 ， 车 返回 NGX_ERROR， 则 表示 失败 。 


调用 ngx_list_push 表 示 添 加 新 的 元 素 ， 传 入 的 参数 是 ngx_list_t 链 
表 。 正 常情 况 下 ， 返 回 的 是 新 分 配 的 元 素 首 地 址 。 如 果 返 回 NULL 空 指 
秆 ， 则 表示 添加 失败 。 在 使 用 它 时 通常 完 调 用 ngx_list_push 得 到 返回 的 
元 和 聚 地 址 ， 再 对 返回 的 地 址 进行 赋值 。 例 如 : 


ngx_str_t* Str = ngx_list_push(testlist); 
if (str == NULL) { 
return NGX_ERROR ; 


str->len= sizeof("Hello world"); 
str->data = "Hello world"; 


过 历 链表 时 Nginx 没 有 提供 相应 的 接口 ， 实 际 上 也 不 需要 。 我 们 可 
以 用 以 下 方法 遍历 链表 中 的 元 素 : 


// part 用 于 指向 链表 中 的 每 一 个 


ngx_list_part_t 数 组 


ngx_list_ part_t* part = &testlist.part; 


// 根据 链表 中 的 数据 类 型 ， 把 数组 里 的 
elts 转 化 为 该 类 型 使 用 


ngx_str_t* str = part->elts,; 
// i 表示 元 素 在 链表 的 每 个 


ngx_1ist_part_t 数 组 里 的 序号 


for (i = 0; /* void */ i++) { 
if (i >= part->nelts) { 
If (part->next == NULL) { 
// 如 果 某 个 


ngx_list_part_t 数 组 的 


next 指 针 为 空 ， 
// 则 说 明 已 经 遍历 完 链表 
break; 
} 
/7 访 同 下 一 个 


ngx_list_ part_t 

part = part->next; 
str = part->elts; 
// 将 


i 序号 置 为 


90， 准备 重新 访问 下 一 个 数组 


i = 0; 


} 
// 这 里 可 以 很 方便 地 取 到 当前 遍历 到 的 链表 元 素 


printf("list element: %*s\n",str[i].len, str[i].data); 


3.2.4 ngx_table_elt_t 数 据 结构 


ngx_table_elt_t 数 据 结构 如 下 所 示 : 


typedef struct { 
ngx_uint_t hash; 
ngx_str_t key; 


ngx_str_t value; 
Uc *]lowcase_key; 
} ngx_table elt_t; 


可 以 看 到 ，ngx_table_elt_t 就 是 一 个 key/value 对 ，ngx_str_t 类 型 的 
key、value 成 员 分 别 存储 的 是 名 字 、 值 字符 串 。hash 成 员 表 明 
ngx_table_elt_t 也 可 以 是 某 个 散 列 表 数 据 结 构 \ngx_hash_t 类 型 ) 中 的 成 
册 。ngx_uint_t 类 型 的 hash 成 员 可 以 在 ngx_hash_t 中 更 快 地 找到 相同 key 
的 ngx_table_elt_t 数 据 。]lowcase_key 指 同 的 是 全 小 写 的 key 字 符 串 。 


显而易见 ，ngx_table_elt_{t 是 为 HTTP 头 部 “ 量 身 订 制 "的 ， 其 中 key 
存储 头 部 名 称 (如 Content-Length) ，value 存 储 对 应 的 值 
(如 “1024”) ，lowcase_key 是 为 了 忽略 HTTP 头 部 名 称 的 大 小 写 ( 例 
如 ， 有 些 客户 端 发 来 的 HTTP 请 求 头 部 是 content-length，Nginx 布 望 它 与 
大 小 写 敏感 的 Content-Length 做 相同 处 理 ， 有 了 全 小 写 的 lowcase_key 成 
员 后 就 可 以 快速 达成 目的 了 ) ，hash 用 于 快速 检索 头 部 ( 它 的 用 法 在 
3.6.3 节 中 进行 详 述 ) 。 


3.2.5 ”ngx_buf tt 数据 结构 


缓冲 区 ngx_buf_t 是 Nginx 处 理 大 数据 的 关键 数据 结构 ， 写 既 应 用 于 
内 存 数据 也 应 用 于 磁盘 数据 。 下 面 主 要 介绍 ngx_buf t 结 构 体 本 号， 而 
摘 述 磁盘 文件 的 ngx_file_t 结 构 体 则 在 3.8.17 中 说 明 。 下 面 来 看 一 下 相 
天 代码 : 


typedef struct ngx_buf_s 
typedef void * 
struct ngx_buf_s { 

/*pos 通 常 是 用 来 告诉 使 用 者 


台 处 理 内 存 中 的 数据 ， 这 样 设 


[能 被 多 次 反复 处 理 。 当 然 ， 


ngx_buf_t; 
ngx_buf_tag_t; 


次 应 该 从 


因为 同一 个 


Foul 


pos 这 个 位 置 


ngx_buf 七 可 


j 它 的 模块 定义 的 


使 


pos 的 含义 是 


*/ 
u_char 
/*last 通 党 


*pos " 


效 的 内 容 到 此 为 止 ， 注 意 ， 


表示 


pos 与 
last 之 间 的 内 存 
的 


nginx 处 理 


SA/ 
u_char 


/* 处 理 文件 时 ， 


*]ast 


file_pos 与 
file_last 的 含义 与 处 理 内 存 时 的 


pos 与 
1ast 相 同 ， 
file_pos 表 示 将 要 处 理 的 文件 位 置 ， 


file_last 表 示 截 止 的 文件 位 置 


ph 
off_t file_pos,; 
off_t file_last,; 
// 如 果 


ngx_buf_t 缓 冲 


区 用 于 内 存 ， 那 么 


start 指 向 这 段 内 存 的 


u_char 
// 与 


起 始 地 址 


*start,; 


start 成 员 对 应 ， 指 向 


u_char 
/* 表 示 当 前 缓冲 


区 的 类 型 ， 例 如 


al 


1 区 内 存 的 末 


*end; 


哪个 模块 使 用 


就 指向 这 个 模块 


ngx_module_t 


的 地 址 


*/ 


ngx_buf_tag_t 


// 引 


的 文件 


tag,; 


ngx_file _t *file 


了 


/* 当 前 缓冲 


12.8 节 描述 的 使 


区 的 影子 缓冲 区 ， 


shadow 成 员 ， 这 


是 因为 


用 缓冲 区 转发 上 游 服务 器 的 响应 时 才 使 用 了 


该 成 员 很 少 用 到 ， 仅 仅 在 


Nginx 太 节约 内 存 了 ， 分 配 一 块 内 存 并 使 用 


ngx_buf_t 表 示 接 收 到 的 上 游 服务 器 响应 后 ， 在 向 下 游客 户 端 转发 时 可 能 会 把 这 块 内 存 存 储 到 文件 


接 向 下 游 发 送 ， 此 时 


Nginx 绝 不 会 重新 复制 一 份 内 存 


ngx_buf_t 结 构 体 指向 原 内 存 ， 这 样 多 个 


ngx_buf_t 结 构 体 指向 了 同一 块 内 存 ， 它 们 之 间 的 关系 就 通 


shadow 成 员 来 引用 。 这 种 设计 过 于 复杂 ， 通 常 不 建议 使 用 
/ 
ngx_buf_t *shadow; 
// 临时 内 存 标志 位 ， 为 
1 时 表示 数据 在 内 存 中 且 这 段 内 存 可 以 修改 
unsigned temporary:1; 
// 标志 位 ,为 
1 时 表示 数据 在 内 存 中 且 这 段 内 存 不 可 以 被 修改 
unsigned memory:1; 
// 标志 位 ,为 
1 时 表示 这 段 内 存 是 


mmap 系 统 调用 映射 过 来 的 ， 不 可 以 被 修改 


unsigned 


// 标志 位 ， 


1 时 表示 可 回收 


unsigned 


// 标志 位 ， 


1 时 表示 这 段 缓 名 区 处 至 


unsigned 


mmap : 工 ; 
为 
recycled :1， 
为 
的 是 文件 而 不 是 内 存 
in_file:1; 


// 标志 位 ,为 


1 时 表示 需要 执行 


flush 操 作 


于 新 的 目的 ， 而 是 再 次 建立 一 个 


TT 


， 也 可 外 


unsigned flush:1; 


/* 标 志 位 ， 对 于 操作 这 块 缓冲 区 时 是 否 使 用 同步 方式 ， 需 谨慎 考虑 ， 这 可 能 会 阻塞 
Nginx 进 程 ， 
Nginx 中 所 有 操作 几乎 都 是 异步 的 ， 这 是 它 支 持 高 并 发 的 关键 。 有 些 框架 代码 在 
sync 为 
1 时 可 能 会 有 阻塞 的 方式 进行 
I/0 操 作 ， 它 的 意义 视 使 用 它 的 
Nginx 模 块 而 定 
*/ 
unsigned sync:1; 
/* 标 志 位 ， 表 示 是 是 最 后 决 缓冲 区 ， 因 为 
ngx_buf_t 可 以 
ngx_chain_t 链 表 串 联 起 来 ， 因 此 ， 当 
last_buf 为 
1 时 ， 表 示 当 前 是 最 后 一 块 待 处 理 的 缓冲 区 
Ww 
unsigned last_buf:1; 
// 标志 位 ， 表 示 是 否 是 
ngx_chain_t 中 的 最 后 一 块 缓冲 区 
unsigned last_in_ chain:1,; 
/* 标 志 位 ， 表 示 是 否 是 最 后 一 个 影子 缓冲 区 ， 与 
shadow 域 配合 使 用 。 通 常 不 建议 使 用 它 
*/ 
unsigned last_shadow:1; 
// 标志 位 ， 表 示 当 前 缓冲 区 是 否 属于 临时 文件 
unsigned temp_file:1; 
}; 


关于 使 用 ngx_buf_t 的 案例 参见 3.7.2 节 。ngx_buf t 是 一 种 基本 数据 


结构 ， 本 质 上 它 提 供 的 仅仅 是 一 


些 指针 成 员 和 标志 位 。 对 于 HTTP 模 块 


来 说 ， 需 要 注意 HTTP 框 架 、 


针 以 及 如 何 处 理 这 些 标志 位 的 ， 


事件 框架 是 如 何 设置 和 使 用 pos、last 等 指 


上 述说 明 只 是 最 常见 的 用 法 。 《如果 


我 们 目 定义 一 个 ngx_buf_t 结 构 体 ， 不 应 当 受 限于 上 述 用 法 ， 而 应 该 根 
据 业 务 需求 自行 定义 。 例 如 ， 在 13.7 节 中 用 一 个 ngx_buf t 缓 冲 区 转发 上 
下 游 TCP 流 时 ，pos 会 指 回 将 要 发 送 到 下 游 的 TCP 流 起 始 地 址 ， 而 last 会 
指向 预备 接收 上 游 TCP 流 的 缓冲 区 起 始 地 址 。) 


3.2.6 ”ngx_chain tt 数据 结构 


ngx_chain_t 是 与 ngx_buf ft 配合 使 用 的 链表 数据 结构 ， 下 面 看 一 下 
它 的 定义 : 
typedef struct ngx_chain_s ngx_chain_t; 
struct ngx_chain s { 
ngx_buf_t *buf; 
ngx_chain t *next; 
}; 
buf 指 向 当前 的 ngx_buf t 绥 冲 区 ，next 则 用 来 指 疝 下 一 个 
ngx_chain_t。 如 果 这 是 最 后 一 个 ngx_chain_t， 则 需要 把 next 置 为 


NULL 。 


在 回 用 户 发 送 HTTP 包 体 时 ， 就 要 传 入 ngx_chain_t 链 表 对 象 ， 注 
， 如 果 是 最 后 一 个 ngx_chain_ t， 那 么 必须 将 next 置 为 NULL ， 人 否则 永 
远 不 会 发 送 成 功 ， 而 且 这 个 请 求 将 一 直 不 会 结束 (Nginx 框 染 的 要 
求 ) 。 


Els 


3.3 如何 将 自己 的 HTTP 模 块 编译 进 Nginx 


Nginx 提 供 了 一 种 简单 的 方式 将 第 三 方 的 模块 编译 到 Nginx 中 。 首 
先 把 源 代码 文件 全 部 放 到 一 个 目录 下 ， 同 时 在 该 目录 中 编写 一 个 文件 
用 于 通知 Nginx 如 何 编译 本 模块 ， 这 个 文件 名 必须 为 config。 它 的 格式 
将 在 3.3.1 节 中 说 明 。 


这 样 ， 只 要 在 configure 脚 本 执行 时 加 入 参数 --add-module=PATH 
(PATH 就 是 上 面 我 们 给 定 的 源 代码 、config 文 件 的 保存 目录 ) ， 束 可 
以 在 执行 正常 编译 安装 流程 时 完成 Nginx 编 译 工 作 。 


有 时 ，Nginx 提 供 的 这 种 方式 可 能 无 法 满足 我 们 的 需求 ， 其 实 ， 在 
执行 完 configure 脚 本 后 Nginx 会 生成 objs/Makefile 和 objs/ngx_modules.c 
文件 ， 完 全 可 以 自己 去 修改 这 两 个 文件 ， 这 是 一 种 更 强大 也 复杂 得 多 
的 方法 ， 我 们 将 在 3.3.3 节 中 说 明 如 何 直接 修改 它们 。 


3.3.1 ”config 文 件 的 写法 


config 文 件 其 实 是 一 个 可 执行 的 Shell 脚 本 。 如 果 只 想 开 发 一 个 
HTTP 模 块 ， 那 么 config 文 件 中 需要 定义 以 下 3 个 变量 : 


ngx_addon_name: 仅 在 configure 执 行 时 使 用 ， 一 般 设 置 为 模块 名 


称 。 


:HTTP_MODULES: 保存 所 有 的 HTTP 模 块 名 称 ， 每 个 HTTP 模 块 
间 由 空格 符 相 连 。 在 重新 设置 HTTP_MODULES 变 量 时 ， 不 要 直接 覆 
盖 它 ， 因 为 configure 调 用 到 自 定义 的 config 脚 本 前 ， 已 经 将 各 个 HTTP 
模块 设置 到 HTTP_MODULES 变 量 中 了 ， 因 此 ， 要 像 如 下 这 样 设置 : 


"$HTTP_MODULES ngx_http_mytest_module" 


:NGX_ADDON_SRCS: 用 于 指定 狐 增 模块 的 源 代码 ， 多 个 待 编译 
的 源 代 码 间 以 空格 符 相 连 ， 在 设置 NGX_ADDON_SRCS 时 可 以 
使 用 $ngx_addon_dir 变 量 ， 它 等 价 于 configure 执 行 时 --add- 


module=PATH 的 PATH 人 参数。 
因此 ， 对 于 mytest 模 块 ， 可 以 这 样 编写 config 文 件 : 


ngx_addon_name=ngx_http_mytest_module 
HTTP_MODULES="$HTTP_MODULES ngx_http_mytest_module" 
NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_mytest_ module.c" 


@@ 注意 ”以 上 3 个 变量 并 不 是 唯一 可 以 在 config 文 件 中 自 定义 的 
部 分 。 如 果 我 们 不 是 开发 HITP 模 块 ， 而 是 开发 一 个 HTTP 过 滤 模 块 ， 
那么 就 要 用 HTTP_FILTER_MODULES 替 代 上 面 的 HTTP_MODULES 变 
量 。 事 实 上， 包括 $CORE MODULES、$EVENT_MODULES、 


$HTTP_MODULES ~ $HTTP_FILTER_MODULES 、 
$HTTP_HEADERS_FILTER_MODULE 等 模块 变量 都 可 以 重 定义 ， 它 
们 分 别 对 应 着 Nginx 的 核心 模块 、 事 件 模 块 、HTTP 模 块 、HTTP 过 滤 模 
块 、HTTP 头 部 过 滤 模 块 。 除 了 NGX_ADDON_SRCS 变 量 ， 或 许 还 有 
一 个 变量 我 们 会 用 到 ， 即 $NGX_ADDON_DEPS 变 量 ， 它 指定 了 模块 
依赖 的 路 径 ， 同 样 可 以 在 config 中 设置 。 


3.3.2 ”利用 configure 脚 本 将 定制 的 模块 加 入 到 Nginx 中 


在 1.6 闻 提 到 的 configure 执 行 流程 中 ， 其 中 有 两 行 脚本 负责 将 第 三 
方 模块 加 入 到 Nginx 中 ， 如 下 所 示 。 


, auto/modules 
. auto/make 


下 面 完 整地 解释 一 下 configure 脚 本 是 如 何 与 3.3.1 市 中 提 到 的 config 
文件 配合 起 来 把 定制 的 第 三 方 模块 加 入 到 Nginx 中 的 。 


0 令 时 ，PATH 就 是 第 三 方 模 
块 所 在 的 路 径 。 在 configure 中 ， 通 过 auto/options 脚 本 设置 了 
NGX_ADDONS 变 量 


--add-module=*) NGX_ADDONS="$NGX_ADDONS $value"™" ;; 


在 configure 命 令 执行 到 auto/modules 脚 本 时 ， 将 在 生成 的 
ngx_modules.c 文 件 中 加 入 定制 的 第 三 方 模块 。 


if test -n "$NGX_ADDONS"; then 
echo configuring additional modules 
for ngx_addon_dir in $NGX_ADDONS 


do 
echo "adding module in $ngx_addon_dir" 
if test -f $ngx_addon dir/config; then 
# 在 这 里 执行 自 定义 的 
config 脚 本 
, $ngx_addon_dir/config 
echo " + $ngx_addon_name was configured" 
else 
echo "$0: error: no $ngx_addon_dir/config was found" 
exit 1 
fi 
done 


fi 


可 以 看 到 ，$NGX_ADDONS 可 以 包含 多 个 日 隶 ， 对 于 每 个 目录 ， 
如 果 其 中 存在 config 文 件 就 会 执行 ， 也 就 是 说 ， 在 config 中 重新 定义 的 
变量 都 会 生效 。 之 后 ，auto/modules 脚 本 开始 创建 hgx_modules.c 文 件 ， 
这 个 文件 的 关键 点 就 是 定义 了 ngx_module_t*+ngx_modules[] 数 组 ， 这 个 
数组 存储 了 Nginx 中 的 所 有 模块 。Nginx 在 初始 化 、 处 理 请 求 时 ， 都 会 
循环 访问 ngx_modules 数 组 ， 确 定 该 用 哪 一 个 模块 来 处 理 。 下 面 来 看 一 
下 auto/modules 是 如 何 生成 数组 的 ， 代 码 如 下 所 示 : 


modules="$CORE_MODULES $EVENT_MODULES" 
If [ $USE_ OPENSSL = YES ]; then 
modules="$modules $0OPENSSL MODULE" 
CORE_DEPS="$CORE_DEPS S$OPENSSL_DEPS" 
CORE_ SRCS="$CORE_SRCS $OPENSSL_SRCS" 
fi 
if [ $HTTP = YES ]; then 
modules="$modules $HTTP_MODULES $HTTP_FILTER_MODULES AN 
$HTTP_HEADERS_FILTER_MODULE AN 


$HTTP_AUX_FILTER_MODULES \ 
$HTTP_COPY_FILTER_MODULE \ 
$HTTP_RANGE_BODY_FILTER MODULE \ 
$HTTP_NOT_MODIFIED_FILTER MODULE" 
NGX_ADDON_DEPS="$NGX_ADDON_DEPS \$(HTTP_DEPS)" 


fi 


首先 ，auto/modules 会 按 顺 序 生成 modules 变 量 。 注 意 ， 这 里 的 
$HTTP_MODULES 等 已 经 在 config 文 件 中 重 定 义 了 。 这 时 ，modules 变 
量 是 包含 所 有 模块 的 。 然 后 ， 开 始 生 成 ngx_modules.c 文 件 : 


cat << END > $NGX_MODULES_C 
#include <ngx_config.h> 

#include <ngx_core.h> 

$NGX_PRAGMA 


END 
for mod in $modules 
do 

echo "extern ngx_module t $mod;" >> $NGX_MODULES_C 
done 
echo >> $NGX_MODULES_C 
echo 'ngx_module _t *ngx_modules[] = {" >> $NGX_MODULES_C 
for mod in $modules 
do 

# 向 


ngx_modules 数 组 里 添加 


Nginx 模 块 
echo " &$mod," >> $NGX_MODULES _C 
done 
cat << END >> $NGX_MODULES_C 
NULL 
}; 
END 


这 样 就 已 经 确定 了 Nginx 在 运行 时 会 调用 上 自 定 义 的 模块 ， 而 
auto/make 脚 本 负责 把 相关 模块 编译 进 Nginx 。 


在 Makefile 中 生成 编译 第 三 方 模块 的 源 代 码 如 下 : 


if test -n "$NGX_ADDON_SRCS"， then 

ngx_cc="\$(CC) $ngx_compile_opt \$(CFLAGS) $ngx_use_pch \$(ALL_INCS)" 
for ngx_src in $NGX_ADDON_SRCS 
do 

ngx_obj="addon/ basename \ dirname $ngx_src\  " 

ngx_obj= “echo $ngx_obj/\ -basename $ngx_src\. \ 

| Sed -e "s/\// $ngx_regex_dirsep/g". 
ngx_obj= “echo $ngx_obj \ 


| sed -e 
"S#A\(.*\.\)cpp\\$#$ngx_objs_dir\1$ngx_objext#g" \ 
-e 
"S#A\(.*\.\)cc\\$#$ngx_objs_dir\1i$ngx_objext#g" \ 
-e 
"S#A\(.*\.\)c\\$#$ngx_objs_dir\1i$ngx_objext#g" \ 
-e 


"S#A\(.*\.\)S\\$#$ngx_objs_dir\1i$ngx_objext#g". 
ngx_src= echo $ngx_src | sed -e "s/\// $ngx_regex_ dirsep/g". 
cat << END >> $NGX_ MAKEFILE 
$ngx_obj: X$(ADDON_DEPS)$ngx_cont$ngx_src 
$ngx_cc$ngx_tab$ngx_objout$ngx_obj$ngx_tab$ngx_src$NGX_AUX 
END 
done 
fi 


下 面 这 段 代码 用 于 将 各 个 模块 的 目标 文件 设置 到 ngx_obj 变 量 中 ， 
紧 挡 着 会 生成 Makefile 里 的 链接 代码 ， 并 将 所 有 的 目标 文件 、 库 文件 
链接 成 二 进 制程 序 。 


for ngx_src in $NGX _ ADDON_SRCS 
do 
ngx_obj="addon/ basename \ dirname $ngx_src\  " 
test -d $NGX_OBJS/$ngx_obj || mkdir -p $NGX_OBJS/$ngx_obj 
ngx_obj= echo $ngx_obj/\ basename $ngx_src\. \ 
| Sed -e "s/\// $ngx_regex_dirsep/g"、 
ngx_all_srcs="$ngx_all_ srcs $ngx_obj" 
done... 


cat << END >> $NGX_ MAKEFILE 
$NGX_OBJS${ngx_dirsep}nginx${ngx_binext}: 
$ngx_deps$ngx_spacer \$(LINK) 
${ngx_long_start}${ngx_binout}$NGX_OBJS${ngx_dirsep}nginx$ngx_long_cont$ngx 
_objs$ngx_libs$ngx_link 
$ngx_rcc 
${ngx_long_end} 
END 


综 上 可 知 ， 第 三 方 模块 吏 是 这 样 代 入 到 Nginx 程 序 中 的 。 


3.3.3 ”直接 修改 Makefile 文 件 


3.3.2 广 中 介绍 的 方法 晤 无 疑问 是 最 方便 的 ， 因 为 大 量 的 工作 已 由 
Nginx 中 的 configure 脚 本 帮 有 我 们 做 好 了 。 在 使 用 其 他 第 三 方 模块 时 ， 一 
般 也 推荐 使 用 该 方法 。 


我 们 有 时 可 能 需要 更 灵活 的 方式 ， 比 如 重新 决定 
ngx_module_t*ngx_modules[] 数 组 中 各 个 模块 的 顺序 ， 或 者 在 编译 源 代 
码 时 需要 加 入 一 些 独特 的 编译 选项 ， 那 么 可 以 在 执行 完 configure 后 ， 
对 生成 的 objsngx_modules.c 和 objs/Makefile 文 件 直接 进行 修改 。 


在 修改 objsngx_modules.c 时 ， 首 移 要 添加 新 增 的 第 三 方 模块 的 声 
明 ， 如 下 所 示 。 


extern ngx_module t ngx_http_mytest_ module; 


其 次 ， 在 合适 的 地 方 将 模块 加 入 到 ngx_modules 数 组 中 。 


ngx_module_t *ngx_ modules[] = { 


&ngx_http_upstream ip_hash module, 
&ngx_http_mytest_module, 
&ngx_http_write filter_module, 


NULL 


注意 ， 模 块 的 顺序 很 重要 。 如 果 同 时 有 两 个 模块 表示 对 同一 个 请 
求 感 兴趣 ， 那 么 只 有 顺序 在 前 的 模块 会 被 调用 。 


修改 objs/Makefile 时 知 要 增加 编译 源 代码 的 部 分 ， 例 如 : 


objs/addon/httpmodule/ngx_http_mytest module.o: $(ADDON_DEPS) \\ 
../Sample/httpmodule// ngx_http_mytest_module.c 
$(CC) -c $(CFLAGS) $(ALL_INCS) \ 
-0 objs/addon/httpmodule/ngx_http_mytest_module.o \ 
../Sample/httpmodule// ngx_http_mytest_module.c 


不 需要 把 目标 文件 链接 到 Nginx 中 ， 例 如 : 


objs/nginx: objs/src/core/nginx.o \ 


objs/addon/httpmodule/ngx_http_mytest_module.o \ 
objs/ngx_modules.o 
$(LINK) -o objs/nginx \ 
objs/src/core/nginx.o \ 


objs/addon/httpmodule/ngx_http_mytest_module.o \ 
objs/ngx_modules.o \ 
-lpthread -lcrypt -lpcre -lcrypto -lcrypto -1z 


请 慎 用 这 种 直接 修改 Makefile 和 ngx_modules.c 的 方法 ， 不 正确 的 
修改 可 能 导致 Nginx 工 作 不 正常 。 


3.4 HTTP 模 块 的 数据 结构 


定义 HTTP 模块 方式 很 帘 单 ， 例 如 : 


ngx_module_t ngx_http_mytest_ module; 


其 中 ，ngx_module_t 是 一 个 Nginx 模 块 的 数据 结构 ( 详 见 8.2 节 ) 。 
下 面 来 分 析 一 下 Nginx 模 块 中 所 有 的 成 员 ， 如 下 所 示 : 


typedef struct ngx_module_s ngx_module_t; 
struct ngx_ module s { 
/* 下 面 的 


ctx_index、 
index、 
spare0、 
sparel、 
spare2、 


spare3、 


version 变 量 不 需要 在 定义 时 赋值 ， 可 以 


Nginx 准 备 好 的 宏 


NGX_MODULE_V1 来 定义 ， 它 已 经 定义 好 了 这 


7 个 值 。 


#define NGX_MODULE_V1 0, 0, 0, 0, 0, 0, 1 
对 于 一 类 模块 (由 下 面 的 


type 成 员 决 定 类 别 ) 而 言 ， 


ctx_index 表 示 当 前 模块 在 这 类 模块 中 的 序号 。 这 个 成 员 常 常 是 由 管理 这 类 模块 的 一 个 


Nginx 核 心 模 块 设置 的 ， 对 于 所 有 的 


HTTP 模 块 而 言 ， 


ctx_index 是 由 核心 模块 


ngx_http_module 设 置 日 


ctx_index 非 常 重要 ， 


jo 


3 4 dd se 它们 既 
5 助 


Nginx 框 架 快速 获得 某 个 模块 的 数据 ( 


HTTP 框 架设 置 


ctx_index 的 过 程 参见 


10 .7 贡 ) 

本 
ngx_uint_t 
/*index 表 示 当 前 模 


ngx_modules 数 组 中 的 序 


ctx_index; 


块 在 


= 


号 。 注 意 ， 


ctx_index 表 示 的 是 当前 模块 在 一 类 模块 中 的 序号 ， 而 


index 表 示 当 前 模块 在 所 


模块 中 的 序号 ， 它 同样 关键 。 


Nginx 启 动 时 会 根据 


ngx_modules 数 组 设置 各 


index 值 。 例 如 : 


ngx_max_module = 0; 


模块 的 


for (i = 0; ngx_ modules[i]; i++) { 
ngx_modules[i]->index = ngx_max_module++; 


} 
</ 
ngx_uint_t 


// spare 系 列 的 保留 


ngx_uint_t 
ngx_uint_t 
ngx_uint_t 
ngx_uint_t 


index; 


变量 ， 暂 未 使 用 


Spareg0 
sparel; 
spare2; 
spare3, 


// 模块 的 版 本 ， 便 了 


ngx_uint_t 


F 将 来 的 扩展 。 目 前 只 有 一 种 ， 默 认为 


version,; 


/*ctx 用 于 指向 一 类 模块 的 上 下 文 结构 体 ， 为 什么 需要 


ctx 呢 ?因为 前 面 说 过 ， 


Nginx 模 块 有 许多 种 类 ， 不 同类 模块 之 间 的 功能 差别 很 大 。 例 如 ， 


I/0 事 件 相 关 的 功能 ， 
HTTP 类 型 的 模块 主要 处 理 


事 人 


于 表达 优先 级 ， 也 用 于 表明 每 个 模块 的 位 置 ， 借 以 


类 型 的 模块 主要 处 理 


HTTP 应 用 层 的 功能 。 这 样 ， 每 个 模块 都 有 了 自己 的 特性 ， 


ctx 将 会 指向 特定 类 型 模块 的 公共 接口 。 例 如 ， 在 


HTTP 模 块 中 ， 


ctx 需 要 指向 


ngx_http_module_t 结 构 体 


*/ 
void *ctx; 
// commands 将 处 理 


nginx.conf 中 的 配置 项 ， 详 见 第 


me 


4 章 


ngx_command_t *commands; 
/*type 表 示 该 模块 的 类 型 ， 它 与 


ctx 指 针 是 紧密 相关 的 。 在 官方 


dtr 


Nginx 中 ， 它 的 取 值 范围 是 以 下 


5 种 : 


NGX_HTTP_MODULE、 
NGX_CORE_MODULE、 
NGX_CONF_MODULE、 
NGX_EVENT_MODULE 、 
NGX_MAIL_MODULE。 这 
5 种 模块 间 的 关系 参考 图 
8-2。 实 际 上 ， 还 可 以 自 定义 新 的 模块 类 型 


ngx_uint_t type,; 
/* 在 

Nginx 的 启动 、 停 止 过 程 中 ， 以 下 

7 个 函数 指针 表示 有 

7 个 执行 点 会 分 别 调 


7 种 方法 (参见 


喜 


8.6 节 ) 。 对 于 任 一 个 方法 而 言 ， 如 果 不 需 要 


Nginx 在 某 个 时 刻 执行 它 ， 那 么 简单 地 把 它 设 为 


NULL 空 指针 即 可 


山 


</ 
/* 虽 然 从 字面 上 理解 应 当 在 


master 进 程 启动 时 回调 


init_master， 但 到 目前 为 止 ， 框 架 代 码 从 来 不 会 调用 它 ， 因 此 ， 可 将 


init_master 设 为 
NULL */ 
ngx_int_t (*init_master)(ngx_log_t *]o0g); 


/*init_module 回 调 方 法 在 初始 化 所 有 模块 时 被 调用 。 在 


master/worker 模 式 下 ， 这 个 阶段 将 在 启动 


worker 子 进程 前 完成 


*/ 
ngx_int_t (*init =m Sng cycle t *cycle); 
/* init_process 回 调 方法 在 正常 服务 前 被 调 


master/worker 模 式 下 ， 多 个 


worker 子 进程 已 经 产生 ， 在 每 个 


worker 进 程 的 初始 化 过 程 会 调用 所 有 模块 的 


init_process 函 数 


*/ 
ngx_int_t (*init_process)(ngx_cycle t *cycle); 
/* 卫生 


Nginx 暂 不 支持 多 线程 模式 ， 所 以 


init_thread 在 框架 代码 中 没有 被 调用 过 ， 设 为 


NULL*/ 
ngx_int_t (*init_ thread)(ngx_cycle t *cycle); 
// 同上 ， 


exit_thread 也 不 支持 ， 设 为 


NULL 
void (*exit_ thread)(ngx_cycle t *cycle); 
。 在 


/* exit_process 回 调 方法 在 服务 停止 前 调用 。 


master/worker 模 式 下 ， 


worker 进 程 会 在 退出 前 调用 它 


*/ 
void (*exit_process)(ngx_cycle t *cycle); 
// exit_master 回 调 方法 将 在 


master 进 程 退出 前 被 调 


void (*exit_ master)(ngx_cycle t *cycle); 


/<* 以 下 


8 个 


Spare_hook 变 量 也 是 保留 字段 ， 目 前 没有 使 用 ， 但 可 用 


Nginx 提 供 的 


NGX_MODULE_V1_PADDING 宏 来 填充 。 看 一 下 该 宏 的 定义 : 


#define NGX_MODULE_V1_PADDING 0, 0, 0, 0, 0, 0, 0, 0*/ 


uintptr_t Spare_hooko0 
uintptr_t spare_hooki1; 
uintptr_t spare_hook2; 
uintptr_t spare_hook3; 
uintptr_t spare_hook4; 
uintptr_t spare_hooks; 
uintptr_t spare_hook6; 
uintptr_t spare_hook7; 


}; 


定义 一 个 HITP 模 块 时 ， 务 必 把 type 字 段 设 为 


NGX_HTITP_ MODULE° 


对 于 下 列 回调 方法 : init_module 、init_process 、exit_process、 
exit_master， 调 用 它们 的 是 Nginx 的 框架 代码 。 换 句 话 说， 这 4 个 回调 
方法 与 HTTP 框 架 无 关 ， 即 使 hginx.conf 中 没有 配置 http{...} 这 种 开启 
HTTP 功 能 的 配置 项 ， 这 些 回调 方法 仍然 会 被 调用 。 因 此 ， 通 常 开发 
HTTP 模 块 时 都 把 它们 设 为 NULL 空 指针 。 这 样 ， 当 Nginx 不 作为 Web 服 
务 器 使 用 时 ， 不 会 执行 HTTP 模 块 的 任何 代码 。 


定义 HTTP 模 块 时 ， 最 重要 的 是 要 设置 ctx 和 commands 这 两 个 成 
员 。 对 于 HTTP 类 型 的 模块 来 说 ，ngx_module_t 中 的 ctx 指 针 必 须 指 向 
ngx_http_module t 接 口 (HTTP 框 架 的 要 求 ) 。 下 面 先 来 分 析 
ngx_http_module t 结 构 体 的 成 员 。 


HTTP 框 架 在 读 取 、 重 载 配 置 文件 时 定义 了 由 ngx_http_module_t 接 
口 描述 的 8 个 阶段 ，HTTP 框 架 在 启动 过 程 中 会 在 每 个 阶段 中 调用 
ngx_http_module t 中 相应 的 方法 。 当 然 ， 如 果 ngx_http_module t 中 的 
某 个 回调 方法 设 为 NULL 空 指针 ， 那 么 HTTP 框 架 是 不 会 调用 它 的 。 


typedef struct { 
// 解析 配置 文件 前 调 


ngx_int_t (*preconfiguration)(ngx_conf_t *cf); 


// 完成 配置 文件 的 解析 后 调用 


ngx_int_t (*postconfiguration)(ngx_conf_t *cf); 


/* 当 需要 创建 数据 结构 用 于 存储 
main 级 别 (直属 于 


http{.,.} 块 的 配置 项 ) 的 全 局 配置 项 时 ， 可 以 通过 


create_main_conf 回 调 方法 创建 存储 全 局 配置 项 的 结构 体 


*/ 
void *(*create main conf)(ngx_conf_t *cf); 
// 常用 于 初始 化 


main 级 别 配置 项 


Char *(*init_main_conf)(ngx_conf t *cf, void *conf); 


/* 当 需要 创建 数据 结构 用 于 存储 


srv 级 别 (直属 于 虚拟 主机 


server{..,.} 块 的 配置 项 ) 的 配置 项 时 ， 可 以 通过 实现 


create_srv_conf 回 调 方 法 创建 存储 


srv 级 别 配置 项 的 结构 体 


*/ 
void *(*create_ srv_conf)(ngx_conf_t *cf)， 
仿 


// ”merge_srv_conf 回 调 方 法 主要 用 于 合 


main 级 别 和 


srv 级 别 下 的 同名 配置 项 


char *(*merge_srv_conf)(ngx_conf_t *cf, void *prev, void *conf); 
于 笃信 


/* 当 需要 创建 数据 结构 用 


loc 级 别 (直属 


locationf{..,.} 块 的 配置 项 ) 的 配置 项 时 ， 可 以 实现 


create_loc_conf 回 调 方法 


*/ 
void *(*create_loc -conf) (ngx— conf_t *cf); 
// ” merge_loc_conf 回 调 方法 主 全 

srv 级 别 和 


loc 级 别 下 的 同名 配置 项 


char *(*merge_loc conf)(ngx_conf_t *cf, void *prev, void *conf); 
} ngx_http_module_t; 


不 过 ， 这 8 个 阶段 的 调用 顺序 与 上 述 定 义 的 顺序 是 不 同 的 。 在 


Nginx 局 动 过 程 中 ，HTTP 框 以 调用 这 些 回调 方法 的 实际 顺序 有 可 能 
这 样 的 〈 与 nginx.conf 配 置 项 有 关 ) 


1) create main conf 
2) create_srv_conf 
3) create_loc_conf 
4) preconfiguration 
5) init main conf 
6) merge_srv_conf 


7) merge_loc_conf 


8) postconfiguration 


commands 数 组 用 于 定义 模块 的 配置 文件 参数 ， 每 一 个 数组 元 素 都 
是 ngx_command t 类 型 ， 数 组 的 结尾 用 ngx_null command 表 示 。Nginx 
在 解析 配置 文件 中 的 一 个 配置 项 时 首先 会 遍历 所 有 的 模块 ， 对 于 每 一 
个 模块 而 言 ， 即 通过 遍历 commands 数 组 进行 ， 另 外 ， 在 数组 中 检查 到 
ngx_null_command 时 ， 会 停止 使 用 当前 模块 解析 该 配置 项 。 每 一 个 
ngx_command_t 结 构 体 定义 了 自己 感 兴趣 的 一 个 配置 项 : 

typedef struct ngx_command s ngx_command_t; 


struct ngx_command_s { 
// 配置 项 名 称 ， 如 


"gzip" 
ngx_str_t name; 
/* 配 置 项 类 型 ， 


type 将 指定 配置 项 可 以 出 现 的 位 置 。 例 如 ， 出 现在 


server{} 或 


location{} 中 ， 以 及 它 可 以 携带 的 参数 个 数 


*/ 
ngx_uint_t type; 
// 出 现 了 


name 中 指定 的 配置 项 后 ， 将 会 调用 


set 方 法 处 理 配置 项 的 参数 


char *(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf); 
// 在 配置 文件 中 的 偏 移 量 


ngx_uint_t conf; 
/* 通 常用 于 使 用 预 设 的 解析 方法 解析 配置 项 ， 这 是 配置 模块 的 一 个 优秀 设计 。 它 需要 与 


conf 配 合 使 用 ， 在 第 


4 章 中 详细 介绍 


*/ 
ngx_uint_t offset,; 
// 配置 项 读 取 后 的 处 理 方法 ， 必 须 是 


ngx_conf_post_t 结 构 的 指针 


void *post; 


}; 


ngx_null _ command 只 是 一 个 空 的 ngx_command t， 如 下 所 示 : 


#define ngx_null command { ngx_null string, 0, NULL, 0, 9, NULL } 


3.5 定义 自己 的 HTTP 模 块 


上 文中 我 们 了 解 了 定义 HITP 模 块 时 需要 定义 哪些 成 员 以 及 实现 哪 
些 方法 ， 但 在 定义 HITP 模 块 前 ， 首 先 需 要 确定 自 定 义 的 模块 应 当 在 什 
么 样 的 场景 下 开始 处 理 用 户 请 求 ， 也 就 是 说 ， 先 要 和 弄 清 楚 我 们 的 模块 
是 如 何 介入 到 Nginx 处 理 用 户 请 求 的 流程 中 的 。 从 2.4 节 中 的 HTTP 配 置 
项 意义 可 知 ， 一 个 HTTP 请 求 会 被 许多 个 配置 项 控制 ， 实 际 上 这 是 因为 
一 个 HTTP 请 求 可 以 被 许多 个 HTTP 模 块 同时 处 理 。 这 样 一 来 ， 肯 定 会 
有 一 个 先后 问题 ， 也 就 是 说 ， 谁 先 处 理 请 求 谁 的 “权力 ”就 更 大 。 例 
如 ，ngx_http_access_module 模 块 的 deny 选 项 一 旦 得 到 满足 后 ，Nginx 
就 会 决定 拒绝 来 自 某 个 IP 的 请 求 ， 后 面 的 诸如 root 这 种 访问 静态 文件 的 
处 理 方式 是 得 不 到 执行 的 。 另 外 ， 由 于 同一 个 配置 项 可 以 从 属于 许多 
个 server、location 配 置 块 ， 那 么 这 个 配置 项 将 会 针对 不 同 的 请 求 起 作 
用 。 因 此 ， 现 在 面临 的 问题 是 ， 我 们 希望 自己 的 模块 在 哪个 时 刻 开 始 
处 理 请 求 ? 是 希望 自己 的 模块 对 到 达 Nginx 的 所 有 请 求 都 起 作用 ， 还 是 
希望 只 对 某 一 类 请 求 (如 URI 匹 配 了 location 后 表达 式 的 请 求 ) 起 作 
用 ? 


Nginx 的 HTTP 框 染 定 义 了 非 第 多 的 用 法 ， 我 们 有 很 大 的 目 由 来 定 
义 目 己 的 模块 如 何 介 入 HTTP 请 求 的 处 理 ， 但 本 草 只 想 说 明 最 简单 、 最 


常见 的 HTTP 模 块 应 当 如 何 编写 ， 因 此 ， 我 们 这 样 定义 第 一 个 HTTP 模 
块 介入 Nginx 的 方式 : 


1) 不 希望 模块 对 所 有 的 HTTP 请 求 起 作用 。 


2) 在 nginx.conf 文 件 中 的 http{}、server{} 或 者 location{} 块 内 定义 
mytest 配 置 项 ， 如 果 一 个 用 户 请 求 通过 主机 域名 、URI 等 匹配 上 了 相应 
的 配置 块 ， 而 这 个 配置 块 下 又 具有 mytest 配 置 项 ， 那 么 希望 mytest 模 块 
开始 处 理 请 求 。 


在 这 种 介入 方式 下 ， 模 块 处 理 请 求 的 顺序 是 固定 的 ， 即 必须 在 
HTTP 框 架 定义 的 NGX_HTTP_CONTENT_PHASE 阶 段 开始 处 理 请 求 ， 
具体 内 容 下 文 详 述 。 


下 面 开 始 按 照 这 种 方式 定义 mytest 模 块 。 首 先 ， 定 义 mytest 配 置 项 
的 处 理 。 从 上 文中 关于 ngx_command_t 结 构 的 说 明 来 看 ， 只 需要 定义 
一 个 ngx_command_t 数 组 ， 并 设置 在 出 现 mytest 配 置 后 的 解析 方法 由 
ngx_http_mytest“ 担 当 ”， 如 下 所 示 : 


static ngx_command_t ngx_http_mytest_ commands[] = { 
{ ngx_string("mytest"), 


NGX_HTTP_MAIN_CONF |NGX_HTTP_SRV_CONF |NGX_HTTP_LOC_CONF|NGX_HTTP_LMT_CONF |NGX_CONF 
_NOARGS, 

ngx_http_mytest, 

NGX_HTTP_LOC_CONF_OFFSET, 

0, 

NULL }, 

ngx_null_command 


其 中 ，ngx_http_mytest 是 ngx_command_t 结 构 体 中 的 set 成 员 〈 完 
整定 义 为 char*(*set) 
(ngx_conf_t*cf,ngx_command_t*cmd,void*conf);) ， 当 在 某 个 配置 块 中 
出 现 mytest 配 置 项 时 ，Nginx 将 会 调用 ngx_http_mytest 方 法 。 下 面 看 一 
下 如 何 实 现 ngx_http_mytest 方 法 。 


static char * 
ngx_http_mytest(ngx_conf_t *cf, ngx_command_t *cmd, void *conf) 


ngx_http_core_loc conf_t *cilcf; 
/* 首 先 找到 


mytest 配 置 项 所 属 的 配置 块 ， 


clcf 看 上 去 像 是 


location 块 内 的 数据 结构 ， 其 实 不 然 ， 它 可 以 是 
main、 
srv 或 者 


loc 级 别 配置 项 ， 也 就 是 说 ， 在 每 个 


http{} 和 
server{} 内 也 都 有 一 个 


ngx_http_core_loc_conf_t 结 构 体 


*/ 
clcf = ngx_http_conf_get module_loc_conf(cf, ngx_http_core_ module),; 
/*HTTP 框 架 在 处 理 用 户 请 求 进行 到 


NGX_HTTP_CONTENT_PHASE 阶 段 时 ， 如 果 请 求 的 主机 域名 、 
URI 与 


mytest 配 置 项 所 在 的 配置 块 相 匹配 ， 就 将 调用 我 们 实现 的 


ngx_http_mytest_handler 方 法 处 理 这 个 请 求 


*/ 
clcf->handler = ngx_http_mytest_handler; 
return NGX_CONF_OK,; 


当 Nginx 接 收 完 HTTP 请 求 的 头 部 信息 时 ， 束 会 调用 HTTP 框 染 处 理 
请 求 ， 另 外 在 11.6 节 描述 的 NGX_HTTP_CONTENT_PHASE 阶 段 将 有 
可 能 调用 mytest 模 块 处 理 请 求 。 在 ngx_http_mytest 方 法 中 ， 我 们 定义 了 
请 求 的 处 理 方法 为 ngx_http_mytest_handler， 举 个 例子 来 说 ， 如 果 用 户 
的 请 求 URI 是 /test/example， 而 在 配置 文件 中 有 这 样 的 location 块 : 


Location /test { 
mytest; 


那么 ，HTTP 框 架 在 NGX_HTTP_CONTENT_PHASE 阶 段 就 会 调用 
到 我 们 实现 的 ngx_http_mytest_handler 方 法 来 处 理 这 个 用 户 请 求 。 事 实 
上 ，HTTP 框 架 共 定义 了 11 个 阶段 (第 三 方 HTTP 模 块 只 能 介入 其 中 的 7 
个 阶段 处 理 请 求 ， 详 见 10.6 闻 ) ， 本 章 只 关注 
NGX_HTTP_CONTENT_PHASE 处 理 阶段 ， 多 数 HTTP 模 块 都 在 此 阶段 
实现 相关 功能 。 下 面 简单 说 明 一 下 这 11 个 阶段 。 


typedef enum { 
// 在 接收 到 完整 的 


HTTP 头 部 后 处 理 的 


HTTP 阶 段 


NGX_HTTP_POST_READ_PHASE = 9， 
/在 还 没有 查询 到 


URI 匹 配 的 


location 前 ， 这 时 


rewrite 重 写 


URL 也 作为 一 个 独立 的 


HTTP 阶 段 

*y 
NGX_HTTP_SERVER_REWRITE_PHASE, 
/* 根 据 


URI 寻 找 匹 配 的 


location， 这 个 阶段 通常 由 


ngx_http_core_module 模 块 实现 ， 不 建议 其 他 


HTTP 模 块 重新 定义 这 一 阶段 的 行为 


</ 
NGX_HTTP_FIND_CONFIG_PHASE, 
/* 在 


NGX_HTTP_FIND_CONFIG_PHASE 阶 段 之 后 重 写 


URL 的 意义 与 


NGX_HTTP_SERVER_REWRITE_PHASE 阶 段 显然 是 不 同 的 ， 
location 块 ( 


location 是 与 


URI 进 行 匹 配 的 ) 


2 
NGX_HTTP_REWRITE_PHASE, 
/这 一 阶段 是 用 于 在 


一 


rewrite 重 写 


URL 后 重新 跳 到 


NGX_HTTP_FIND_CONFIG_PHASE 阶 段 ， 找 到 与 新 的 


URI 匹 配 的 


location。 所 以 ， 这 一 阶段 是 无 法 由 第 三 方 


HTTP 模 块 处 理 的 ， 而 仅 


ngx_http_core_module 模 块 使 


yh 
NGX_HTTP_POST_REWRITE_PHASE, 
// 处 理 


NGX_HTTP_ACCESS_PHASE 阶 段 前 ， 


HTTP 模 块 可 以 介入 的 处 理 阶 段 


NGX_HTTP_PREACCESS_PHASE, 
A/* 这 个 阶段 用 于 让 


HTTP 模 块 判断 是 否 允 许 这 个 请 求 访问 


因为 这 


者 会 导致 查找 到 不 同 的 


Nginx 服 务 器 


NGX_HTTP_ACCESS_PHASE, 


/* 当 


NGX_HTTP_ACCESS_PHASE 阶 段 中 


HTTP 模 块 的 


五 


handler 处 理 方法 返回 不 允许 访问 的 错误 码 时 (实际 是 


NGX_HTTP_FORBIDDEN 或 者 


[IO 
MA 


NGX_HTTP_UNAUTHORIZED) ， 这 个 阶段 将 负责 构造 


NGX_HTTP_ACCESS_PHASE 阶 段 收尾 


4 


HTTP 请 求 访问 静态 文件 资源 时 ， 


try_files 配 置 项 可 以 使 这 个 请 求 顺序 地 访问 多 个 静态 文件 资源 ， 如 果 某 一 次 访问 失败 ， 则 继续 访问 


try_files 中 指定 的 下 一 个 静态 资源 。 另 外 ， 这 个 功能 完 


NGX_HTTP_TRY_FILES_PHASE 阶 段 中 实现 的 


NGX_HTTP_TRY_FILES_PHASE, 
// 用 于 处 理 


HTTP 请 求 内 容 的 阶段 ， 这 是 大 部 分 


HTTP 模 块 最 喜欢 介入 的 阶段 


NGX_HTTP_CONTENT_PHASE, 
/* 处 理 完 请 求 后 记录 日 志 的 阶段 。 例 如 ， 


ngx_http_log_module 模 块 就 在 这 个 阶段 中 加 入 了 一 个 


handler 处 理 方法 ， 使 得 每 个 


HTTP 请 求 处 理 完毕 后 会 记录 


access_1og 日 志 


*/ 
NGX_HTTP_LOG_PHASE 
} ngx_http_phases ; 


色 服务 的 


全 是 在 


户 响 应 。 所 以 ， 这 个 阶段 实际 上 


时针 


当然 ， 用 户 可 以 在 以 上 11 个 阶段 中 任意 选择 一 个 阶段 让 mytest 模 
块 介 入 ， 但 这 需要 学 习 完 第 10 章 、 第 11 章 的 内 容 ， 完 全 熟悉 了 HTTP 框 


架 的 处 理 流程 后 才 可 以 做 到 。 


暂且 不 管 如 何 实现 处 理 请 求 的 ngx_http_mytest_handler 方 法 ， 如 果 
没有 什么 工作 是 必须 在 HTTP 框架 初始 化 时 完成 的 ， 那 束 不 必 实 现 
ngx_http_module t 的 8 个 回调 方法 ， 可 以 像 下 面 这 样 定义 


ngx_http_module _t 接 口 。 


static ngx_http_module t ngx_http_mytest module ctx = { 


NULL， /* preconfiguration */ 

NULL， /* postconfiguration */ 

NULL， /* create main configuration */ 
NULL， /* init main configuration */ 

NULL， /* Create server configuration */ 
NULL， /* merge Server configuration */ 
NULL， /* create Location configuration */ 
NULL /* merge location configuration */ 


}; 


最 后 ， 定 义 mytest 模 块 : 


ngx_module _t ngx_http_mytest module = { 
NGX_MODULE_V1, 


&ngx_http_mytest_module_ctx, /* module context */ 
ngx_http_mytest_commands, /* module directives */ 
NGX_HTTP_MODULE, /* module type */ 

NULL, /* init master */ 

NULL, /* init module */ 

NULL， /* init process */ 
NULL, /* init thread */ 

NULL, /* exit thread */ 

NULL， /* exit process */ 
NULL, /* exit master */ 


NGX_MODULE_V1_PADDING 
】 


这 样 ，mytest 模 块 在 编译 时 将 会 被 加 入 到 ngx_modules 全 局 数组 
中 。Nginx 在 启动 时 ， 会 调用 所 有 模块 的 初始 化 回调 方法 ， 当 然 ， 这 个 
例子 中 我 们 没有 实现 它们 (也 没有 实现 HTTP 框 架 初 始 化 时 会 调用 的 
ngx_http_module t 中 的 8 个 方法 ) 。 


3.6 ”处 理 用 户 请 求 


本 节 介 绍 如 何 处 理 一 个 实际 的 HTTP 请 求 。 回 顾 一 下 上 文 ， 在 出 现 
mytest 配 置 项 时 ，ngx_http_mytest 方 法 会 被 调用 ， 这 时 将 
ngx_http_core_loc_conf t 结 构 的 handler 成 员 指定 为 
ngx_http_mytest_handler， 另 外 ，HITTP 框 架 在 接收 完 HITTP 请 求 的 头 部 
后 ， 会 调用 handler 指 癌 的 方法 。 下 面 看 一 下 handler 成 员 的 原型 
ngx_http_handler_pt 


typedef ngx_int_t (*ngx_http_handler_pt)(ngx_http_request t *r); 


从 上 面 这 段 代 码 可 以 看 出 ， 实 际 处 理 请 求 的 方法 
ngx_http_mytest_handler 将 接收 一 个 ngx_http_request_t 类 型 的 参数 r， 返 
回 一 个 ngx_int_t (参见 3.2.1 节 ) 类 型 的 结果 。 下 面 先 探讨 一 下 
ngx_http_mytest_handler 方 法 可 以 返回 什么 ， 再 看 一 下 参数 r 包 含 了 哪 
些 Nginx 已 经 解析 完 的 用 户 请 求 信息 。 


3.6.1 处理 方法 的 返回 值 


返回 值 可 以 是 HTTP 中 啊 应 包 的 运 回 码 ， 其 中 包括 了 HTTP 框 
ee ， 如 下 所 示 。 


#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 


NGX_HTTP_OK 

NGX_HTTP_CREATED 
NGX_HTTP_ACCEPTED 
NGX_HTTP_NO_CONTENT 
NGX_HTTP_PARTIAL_CONTENT 
NGX_HTTP_SPECIAL_RESPONSE 
NGX_HTTP_MOVED_PERMANENTLY 
NGX_HTTP_MOVED_TEMPORARILY 
NGX_HTTP_SEE_OTHER 
NGX_HTTP_NOT_MODIFIED 
NGX_HTTP_TEMPORARY_REDIRECT 
NGX_HTTP_BAD_REQUEST 
NGX_HTTP_UNAUTHORIZED 
NGX_HTTP_FORBIDDEN 
NGX_HTTP_NOT_FOUND 
NGX_HTTP_NOT_ALLOWED 
NGX_HTTP_REQUEST_TIME_OUT 
NGX_HTTP_CONFLICT 
NGX_HTTP_LENGTH_REQUIRED 
NGX_HTTP_PRECONDITION_FAILED 
NGX_HTTP_REQUEST_ENTITY_TOO_LARGE 
NGX_HTTP_REQUEST_URI_TOO_LARGE 
NGX_HTTP_UNSUPPORTED_MEDIA_TYPE 
NGX_HTTP_RANGE_NOT_SATISFIABLE 


411 
412 
413 
414 
415 
416 


/* The special code to close connection without any response */ 


#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 


NGX_HTTP_CLOSE 
NGX_HTTP_NGINX_CODES 
NGX_HTTP_REQUEST_HEADER_TOO_LARGE 
NGX_HTTPS_CERT_ERROR 
NGX_HTTPS_NO_CERT 
NGX_HTTP_TO_HTTPS 
NGX_HTTP_CLIENT_CLOSED_REQUEST 
NGX_HTTP_INTERNAL_SERVER_ERROR 
NGX_HTTP_NOT_IMPLEMENTED 
NGX_HTTP_BAD_GATEWAY 
NGX_HTTP_SERVICE_UNAVAILABLE 
NGX_HTTP_GATEWAY_TIME_OUT 
NGX_HTTP_INSUFFICIENT_STORAGE 


@ 注意 ”以 上 返回 值 除了 REFC2616 规 范 中 定义 的 返回 码 外 ， 还 
有 Nginx 目 身 定义 的 HTTP 返 回 码 。 例 如 ，NGX_HTTP_CLOSE 束 是 用 


于 要 求 HTTP 框 架 直 接 关 闭 用 户 连接 的 。 


在 ngx_http_mytest_handler 的 返回 值 中 ， 如 果 是 正常 的 HTTP 返 回 


码 ，Nginx 距 会 按照 规范 构造 合法 的 啊 应 包 发 送 


于 PUT 方法 暂 不 文 持 ， 那 么 ， 在 处 理 方法 中 发 现 方法 名 是 PUT 时 ， 


全 用户 。 例 如 ， 假 设 对 


回 NGX_HTTP_NOT_ALLOWED， 这 样 Nginx 也 就 会 构造 类 似 下 面 的 
响应 包 给 用 户 。 


http/1.1 405 Not Allowed 

Server: nginx/1.0.14 

Date: Sat, 28 Apr 2012 06:07:17 GMT 
Content-Type: text/html 

Content-Length: 173 

Connection: keep-alive 

<html> 

<head><title>405 Not Allowed</title></head> 
<body bgcolor="white"> 

<Center><h1>405 Not Allowed</h1i></center> 
<hr><center>nginx/1.0.14</center> 

</body> 

</html> 


在 处 理 方法 中 除了 返回 HTTP 响 应 码 外 ， 还 可 以 返回 Nginx 全 局 定 
义 的 几 个 错误 码 ， 包 括 : 


#define NGX_OK 
#define NGX_ERROR 
#define NGX_AGAIN 
#define NGX_BUSY 
#define NGX_DONE 
#define NGX_DECLINED 
#define NGX_ABORT 


sh Og, Mg Ml 
OROOVONPO 


这 些 错 误 码 对 于 Nginx 自 身 提供 的 大 部 分 方法 来 说 都 是 通用 的 。 所 
以 ， 当 我 们 最 后 调用 ngx_http_output_filter (参见 3.7 节 ) 向 用 户 发 送 响 
应 包 时 ， 可 以 将 ngx_http_output_filter 的 返回 值 作为 
ngx_http_mytest_handler 方 法 的 返回 值 使 用 。 例 如 ; 


static ngx_int _t ngx_http_mytest_handler(ngx_http_request t *r) 
{ 


ngx_int_t rc = ngx_http_send_header(r); 
If (rc == NGX_ERROR || rc > NGX OK || r->header_only) { 
return rc; 


} 
return ngx_http_output_filter(r, &out); 


} 


当然 ， 直 接 返 回 以 上 7 个 通用 值 也 是 可 以 的 。 在 不 同 的 场景 
7 个 通用 返回 值 代表 的 含义 不 尽 相同 。 在 mytest 的 例子 中 ，HTTP 框 染 
在 NGX_HTTP_CONTENT_PHASE 阶 段 调用 ngx_http_mytest_handler 
后 ， 会 将 ngx_http_mytest_handler 的 返回 值 作为 参数 传 给 
ngx_http_finalize_request 方 法 ， 如 下 所 示 。 


if (r->content_handler) { 
r->write_event_handler = ngx_http_request_empty_handler; 
ngx_http_finalize_request(r, r->content_handler(r)); 
return NGX_OK; 


上 面 的 r->content_handler 会 指向 ngx_http_mytest_handler 处 理 方 
法 。 也 束 是 说 ， 事 实 上 ngx_http_finalize_request 决 定 了 
ngx_http_mytest_handler 如 何 起 作用 。 本 章 不 探讨 
ngx_http_finalize_requestb 实现 〈 详 见 11.10 节 ) ， 只 简单 地 说 明 一 下 4 
个 通用 返回 码 ， 男 外 ， 在 11.10 廊 中 介绍 这 4 个 返回 码 引 发 的 Nginx 一 系 
列 动作 。 


NGX_OK: 表示 成 功 。Nginx 将 会 继续 执行 该 请 求 的 后 续 动作 
(如 执行 subrequest 或 撤销 这 个 请 求 ) 。 


.NGX_DECLINED: 继续 在 NGX_HTTP_CONTENT PHASE 阶段 
寻找 下 一 个 对 于 该 请 求 感 兴趣 的 HTTP 模 块 来 再 次 处 理 这 个 请 求 。 


NGX_DONE: 表示 到 此 为 止 ， 同 时 HTTP 框 架 将 暂时 不 再 继续 执 
行 这 个 请 求 的 后 续 部 分 。 事 实 上 ， 这 时 会 检查 连接 的 类 型 ， 如 果 是 
keepalive 类 型 的 用 户 请 求 ， 就 会 保持 住 HTTP 连 接 ， 然 后 把 控制 权 交 给 
Nginx。 这 个 返回 码 很 有 用 ， 考 虚 以 下 场景 在 一 个 请 求 中 我 们 必须 访 
问 一 个 耗 时 极 长 的 操作 (比如 某 个 网 络 调用 ) ， 这 样 会 阻塞 住 Nginx， 
又 因为 我 们 没有 把 控制 权 交 还 给 Nginx， 而 是 在 
ngx_http_mytest_handler 中 让 Nginx worker 进 程 休眠 了 (如 等 待 网 络 的 
回 包 ) ， 所 以 ， 这 就 会 导致 Nginx 出 现 性 能 问题 ， 该 进程 上 的 其 他 用 户 
请 求 也 得 不 到 响应 。 可 如 果 我 们 把 这 个 耗 时 极 长 的 操作 分 为 上 下 两 个 
部 分 (就 像 Linux 内 核 中 对 中 断 处 理 的 划分 ) ， 上 半 部 分 和 下 半 部 分 都 
是 无 阻塞 的 〈 耗 时 很 少 的 操作 ) ， 这 样 ， 在 ngx_http_mytest_handler 进 
入 时 调用 上 半 部 分 ， 然 后 返回 NGX_DONE， 把 控制 交还 给 Nginx， 从 
而 让 Nginx 继 续 人 处理 其 他 请 求 。 在 下 半 部 分 被 触发 时 (这 里 不 探讨 具体 
的 实现 方式 ， 事 实 上 使 用 upstream 方 式 做 反 向 代理 时 用 的 就 是 这 种 思 
想 ) ， 再 回调 下 半 部 分 处 理 方法 ， 这 样 就 可 以 保证 Nginx 的 高 性 能 特性 


了 。 如 果 需 要 彻底 了 解 NGX_DONE 的 意义 ， 那 么 必须 学 习 第 11 章 内 
容 ， 其 中 还 涉及 请 求 的 引用 计数 内 容 。 


.NGX_ERROR: 表示 错误 。 这 时 会 调用 ngx_http_terminate_request 
终止 请 求 。 如 有 果 还 有 POST 子 请 求 ， 那 么 将 会 在 执行 完 POST 请 求 后 再 
终止 本 次 请 求 。 


3.6.2 ”获取 URI 和 参数 


请 求 的 所 有 信息 〈 如 方法 、URI、 协 议 版 本 号 和 头 部 等 ) 都 可 以 
在 传 入 的 ngx_http_request_t 类 型 参数 r 中 取得 。ngx_http_request_t 结 构 
体 的 内 容 很 多 ， 本 节 不 会 探讨 ngx_http_request_t 中 所 有 成 员 的 意义 
ngx_http_request_t 结 构 体 中 的 许多 成 员 只 有 HTTP 框 架 才 感 兴趣 ， 在 
11.3.1 节 会 更 详细 的 说 明 ) ， 只 介绍 一 下 获取 URI 和 参数 的 方法 ， 这 非 
常 简 单 ， 因 为 Nginx 提 供 了 多 种 方法 得 到 这 些 信息 。 下 面 先 介绍 相关 成 
员 的 定义 。 


typedef struct ngx_http_request_s ngx_http_request_t,; 
struct ngx_http_request_Ss { 


ngx_uint_t method,; 
ngx_uint_t http_version,; 
ngx_str_t request_line; 
ngx_str_t Uri; 

ngx_str_t args; 
ngx_str_t exten; 
ngx_str_t unparsed_uri,; 
ngx_str_t method_name; 
ngx_str_t http_protocol; 
u_char *uri_start; 
u_char *uri_end; 
u_char *uri_ext; 
u_char *args_start,; 
u_char *request_start,; 
u_char *request_end,; 
u_char *method_end,; 
u_char *schema_start,; 
u_char *schema_end; 


}; 


在 对 一 个 用 户 请 求 行进 行 解析 时 ， 可 以 得 到 下 列 4 类 信息 。 


(1) 方法 名 


method 的 类 型 是 ngx_uint_t (无 符号 整 型 )， 它 是 Nginx 名 上 略 大 小 
写 等 情形 时 解析 完 用 户 请 求 后 得 到 的 方法 类 型 ， 其 取 值 范围 如 下 所 


小 ° 


#define NGX_HTTP_UNKNOWN 0OX0001 
#define NGX_HTTP_GET OX0002 
#define NGX_HTTP_HEAD OX0004 
#define NGX_HTTP_POST 0OX0008 
#define NGX_HTTP_PUT 0OX0010 
#define NGX_HTTP_DELETE 0OX0020 
#define NGX_HTTP_MKCOL 0OX0040 
#define NGX_HTTP_COPY 0OXx0080 
#define NGX_HTTP_MOVE 0OX0100 
#define NGX_HTTP_OPTIONS 0OX0200 
#define NGX_HTTP_PROPFIND Ox0400 
#define NGX_HTTP_PROPPATCH Ox0800 
#define NGX_HTTP_LOCK Ox1000 
#define NGX_HTTP_UNLOCK Ox2000 
#define NGX_HTTP_TRACE Ox4000 


当 需 要 了 人 解 用 户 请 求 中 的 HTTP 方 法 时 ， 应 该 使 用 tr->method 这 个 
整 型 成 员 与 以 上 15 个 宏 进行 比较 ， 这 样 速度 是 最 快 的 (如 果 使 用 
method_name 成 员 与 字符 串 做 比较 ， 那 么 效率 会 差 很 多 ) ， 大 部 分 情 
况 下 推荐 使 用 这 种 方式 。 除 此 之 外 ， 还 可 以 用 method_name 取 得 用 户 
请 求 中 的 方法 名 字符 串 ， 或 者 联合 request_start 与 method_end 指 针 取 得 
方法 名 。method_name 是 ngx_str_t 类 型 ， 按 照 3.2.2 市 中 介绍 的 方法 使 用 
即 可 。 


reduest_start 与 method_end 的 用 法 也 很 简单 ， 其 中 request_start 指 回 
用 户 请 求 的 首 地 址 ， 同 时 也 是 方法 名 的 地 址 ，method_end 指 同方 法 名 


的 最 后 一 个 字符 (注意 ， 这 点 与 其 他 xxx_end 指 针 不同 ) 。 获 取 方 法 名 
时 可 以 从 request_start 开 始 回 后 遇 历 ， 直 到 地 址 与 method_end 相 同 为 
止 ， 这 段 内 存 存 储 着 方法 名 。 


@@ 注意 ”Nginx 中 对 内 存 的 控制 相当 严格 ， 为 了 和 避免 不 必要 的 内 
存 开销 ， 许 多 需要 用 到 的 成 员 都 不 是 重新 分 配 内 存 后 存储 的 ， 而 是 直 
接 指向 用 户 请 求 中 的 相应 地 址 。 例 如 ，method_name data 、 
request_start 这 两 个 指针 实际 指向 的 都 是 同一 个 地 址 。 而 且 ， 因 为 它们 
是 简单 的 内 存 指针 ， 不 是 指向 字符 串 的 指针 ， 所 以 ， 在 大 部 分 情况 
下 ， 都 不 能 将 这 些 u_charx 指 针 当做 字符 串 使 用 。 


(2) URI 


ngx_str_t 类 型 的 uri 成 员 指向 用 户 请 求 中 的 URI。 同 理 ，u_char* 类 
型 的 uri_start 和 uri_end 也 与 request_start、method_end 的 用 法 相似 ， 唯 一 
不 同 的 是 ，method_end 指 同方 法 名 的 最 后 一 个 字符 ， 而 uri_end 指 癌 
URI 结 束 后 的 下 一 个 地 址 ， 也 就 是 最 后 一 个 字符 的 下 一 个 字符 地 址 
(HTTP 框 架 的 行为 ;， 这 是 大 部 分 u_char* 类 型 指针 


对 “xxx_start” 和 “xxx_end” 谈 量 的 用 法 。 


ngx_str_t 类 型 的 exten 成 员 指 向 用 户 请 求 的 文件 扩展 名 。 例 如 ， 在 
访问 “GET/a.txt HTTP/1.1” 时 ，exten 的 值 是 {len=3,data="txt"}， 而 在 访 
问 “GET/a HTTP/1.1” 有 时 ，exten 的 值 为 空 ， 也 就 是 {len=0,data=0x0}。 


Uri_ext 指 针 指 回 的 地 址 与 exten.data 相 同 。 


unparsed_uri 表 示 没 有 进行 URL 解 码 的 原始 请 求 。 例 如 ， 当 wri 为 “/a 
b” 时 ，unparsed_uri 是 “/a9%20b” (空格 字符 做 完 编码 后 是 %20) 。 


(3) URL 参 数 


args 指 向 用 户 请 求 中 的 URL 参 数 。 


args_start 指 癌 URL 参 数 的 起 始 地 址 ， 配 合 uri_ end 使 用 也 可 以 获得 
URL 参 数 。 


(4) 协议 版 本 


http_protocol 的 data 成 员 指 辐 用 户 请 求 中 HTTP 协 议 版 本 字符 串 的 
起 始 地 址 ，len 成 员 为 协议 版 本 字符 串 长 度 。 


http_version 是 Nginx 解 析 过 的 协议 版 本 ， 它 的 取 值 范围 如 下 : 


#define NGX_HTTP_VERSION_9 9 
#define NGX_HTTP_VERSION_10 1000 
#define NGX_HTTP_VERSION 11 1001 


建议 使 用 http_version 分 析 HTTP 的 协议 版 本 。 


最 后 ， 使 用 request_start 和 request_end 可 以 获取 原始 的 用 户 请 求 


休 。 


3.6.3 ”获取 HTTP 头 部 


在 ngx_http_request_tsr 中 残 可 以 取 到 请 求 中 的 HITP 头 部 ， 比 如 使 
用 下 面 的 成 员 : 


struct ngx_http_request_Ss { 


ngx_buf_t 


*header_in; 
ngx_http_headers_in_t 


headers_in,; 


}; 


其 中 ，header_in 指 向 Nginx 收 到 的 未 经 解析 的 HTTP 尖 部， 这 里 暂 


不 关注 它 〈 在 第 11 章 中 可 以 看 到 ，header_in 就 是 接收 HITP 头 部 的 缓冲 


区 ) 。ngx_http_headers_in_t 类 型 的 headers_in 则 存储 已 经 解析 过 的 


HTTP 尖 部。 下面 介绍 ngx_http_headers_in_t 结 构 体 中 的 成 员 


O 


typedef Struct { 
/* 所 有 解析 过 的 


HTTP 头 部 都 在 


headers 链 表 中 ， 可 以 使 


3.2.3 节 中 介绍 的 遍历 链表 的 方法 来 获取 所 有 的 


HTTP 头 部 。 注 意 ， 这 里 


headers 链 表 的 每 一 个 元 素 都 是 


3.2.4 节 介绍 过 的 
ngx_table_elt_t 成 员 


5 
ngx_list_t 


headers; 
/* 以 下 每 


> 


ngx_table_elt_t 成 员 都 是 
RFC2616 规 范 中 定义 的 
HTTP 头 部 ， 

它们 实际 都 指向 


headers 链 表 中 的 相应 成 员 。 注 ; 


让 


， 当 它们 为 


NULL 空 指针 时 ， 表 示 没 有 解析 到 相应 的 


HTTP 头 部 


*/ 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table_ elt_t 

#if (NGX_HTTP_GZIP) 
ngx_table elt_t 
ngx_table_ elt_t 

#endif 
ngx_table elt_t 
ngx_table elt_t 


*host,; 
*connection; 
*if_modified_since; 


*if_unmodified_since; 


*USer_agent 
*referer 
*content_length; 
*content_type; 
*range; 

*if_range; 
*transfer_encoding; 
*expect; 


*accept_encoding; 
*Vvia,; 


*authorization; 
*keep_alive,; 


#if (NGX_HTTP_PROXY || NGX_HTTP_REALIP | | NGX_HTTP_GEO) 


ngx_table elt_t 
#endif 
#if (NGX_HTTP_REALIP) 
ngx_table elt_t 
#endif 
#if (NGX_HTTP_HEADERS ) 
ngx_table elt_t 
ngx_table elt_t 
#endif 
#if (NGX_HTTP_DAV) 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
#endif 
/*user 和 


passwd 是 只 有 


ngx_http_auth_basic_module 才 会 


*/ 
ngx_str_t 
ngx_str_t 
/*coOkies 是 以 


ngx_array_t 数 组 存储 的 ， 本 章 先 不 介 


数 于 


*x_forwarded_for; 


*x_real_ip; 


*accept; 
*accept_language; 


*depth; 
*destination,; 
*overwrite; 
*date; 


员 ， 这 里 可 以 忽略 


USer ; 
passwd 


居 结 构 ， 感 兴趣 的 话 可 以 直接 跳 到 


7.3 节 了 解 


ngx_array_t 的 相关 用 法 

人 水 
ngx_array_t cookies; 
// server 名 称 
ngx_str_t server; 


// 根据 


ngx_table_elt_t *content_length 计 算出 的 


HTTP 包 体 大 小 
off_t content_length_n; 
time_t keep_alive_n; 


/*HTTP 连 接 类 型 ， 它 的 取 值 范围 是 


OO、 


NGX_http_CONNECTION_CLOSE 或 者 


NGX_HTTP_CONNECTION_KEEP_ALIVE*/ 
unsigned connection_type:2; 
A/* 以 下 
7 个 标志 位 是 
HTTP 框 架 根据 浏览 器 传 来 的 “ 
useragent” 头 部 ， 它 们 可 用 来 判断 浏览 器 的 类 型 ， 值 为 


1 时 表示 是 相应 的 浏览 器 发 来 的 请 求 ， 值 为 


9 时 则 相反 

*/ 
unsigned msie:1; 
unsigned msie6:1; 
unsigned opera:1; 
unsigned gecko:1; 
unsigned chrome:1; 
unsigned safari:1; 
unsigned konqueror:1; 


} ngx_http_headers_ in_t; 


获取 HTTP 头 部 时 ， 有 直接 使 用 r>headers_ in 的 相应 成 员 束 可 以 了 。 
这 里 举例 说 明 一 下 如 何 通过 遍历 headers 链 表 获 取 非 RFC2616 标 准 的 
HTTP 头 部 ， 读 者 可 以 先 回 顾 一 下 ngx_list_t 链 表 和 ngx_table_elt_t 结 构 


体 的 用 法 。 前 面 3.2.3 节 中 已 经 介绍 过 ，headers 是 一 个 ngx_list_t 链 表 ， 

它 存 储 着 解析 过 的 所 有 HTTP 头 部 ， 链 表 中 的 元 素 都 是 ngx_table_elt { 

类 型 。 下 面 答 试 在 一 个 用 户 请 求 中 找到 “Rpc-Description” 头 部 ， 首 先 判 

盯 其 值 是 否 为 “uploadFile”， 再 决定 后 续 的 服务 需 行 为 ， 代 码 如 下 。 
ngx_list part_t *part = &r->headers_in.headers.part; 


ngx_table elt t *header = part->elts; 
// 开始 遍历 链表 


for (i = 0; /* void */; I++) { 
// 判断 是 否 到 达 链 表 中 当前 数组 的 结尾 处 


if (i >= part->nelts) { 
// 是 否 还 有 下 一 个 链表 数组 元 素 


if (part->next == NULL) { 
break; 


} 

/* part 设 置 为 
next 来 访问 下 一 个 链表 数组 ，; 
header 也 指向 下 一 个 链表 数组 的 首 地 址 ; 


i 设置 为 


9 时 ， 表 示 从 头 开始 遍历 新 的 链表 数组 


7 
part = part->next,; 
header = part->elts; 
i = 0; 


} 
// hash 为 


9 时 表示 不 是 合法 的 头 部 


If (header[il].hash == 0) { 
continue 


} 
/* 判 断 当前 的 头 部 是 否 是 “ 


Rpc-Description”。 如 果 想 要 忽略 大 小 写 ， 则 应 该 先 


| 


header[i].1Lowcase_key 代 替 


header[i].key.data， 然 后 比较 字符 串 


* 
/ 
If (0 == ngx_strncasecmp(header[i].key.data, 
(u_char*) "Rpc-Description", 
header[i].key.1en)) 


{ 
// 判断 这 个 


HTTP 头 部 的 值 是 否 是 “ 
uploadFile” 
if (0 == ngx_strncmp(header[i].value.data, 


"uploadFile", 
header[i].value.1en)) 


// 找到 了 正确 的 头 部 ， 继 续 向 下 执行 


对 于 和 常见 的 HTTP 头 部 ， 直 接 获 取 r->headers_in 中 已 经 由 HTTP 框 
架 解 析 过 的 成 员 即 可 ， 而 对 于 不 常见 的 HTTP 尖 部， 需要 授 历 r- 
>headers_in.headers 链 表 才 能 获得 。 


3.6.4 获取 HTTP 包 体 


HTTP 包 体 的 长 度 有 可 能 非常 大 ， 如 采 试 图 一 次 性 调用 并 读 取 完 所 
有 的 包 体 ， 那 么 多 半 会 了 蛆 寨 Nginx 进 程 。HTTP 框 架 提 供 了 一 种 方法 来 
异步 地 接收 包 体 : 


ngx_int_t ngx_http_read client request_ body(ngx_http_request _t *r, 
ngx_http_client_ body_handler_pt post_handler); 


ngx_http_read_client_request_body 是 一 个 异步 方法 ， 调 用 它 只 是 说 
明 要 求 Nginx 开 始 接收 请 求 的 包 体 ， 并 不 表示 是 否 已 经 接收 完 ， 当 接收 
完 所 有 的 包 体内 容 后 ，post_handler 指 向 的 回调 方法 会 被 调用 。 因 此 ， 
即使 在 调用 了 ngx_http_read_client_request_body 方 法 后 它 已 经 返回 ， 也 
无 法 确定 这 时 是 否 已 经 调用 过 post_handler 指 癌 的 方法 。 换 人 句 话 说 ， 
ngx_http_read_client_request_body 返 回 时 既 有 可 能 已 经 接收 完 请 求 中 所 
有 的 包 体 《假如 包 体 的 长 度 很 小 ，， 也 有 可 能 还 没 开 始 接收 包 体 。 如 
果 ngx_http_read_client_request_body 是 在 ngx_http_mytest_handler 处 理 
方法 中 调用 的 ， 那 么 后 者 一 般 要 返回 NGX_DONE， 因 为 下 一 步 束 是 将 
它 的 返回 值 作为 参数 传 给 ngx_http_finalize_request。NGX_DONE 的 意 


义 在 3.6.1 廊 中 已 经 介绍 过 ， 这 里 不 再 和 玖 述 。 


下 面 看 一 下 包 体 接收 完毕 后 的 回调 方法 原型 
ngx_http_client_body_handler_pt 是 如 何 定 义 的 : 


typedef void (*ngx_http_client_ body_handler_pt)(ngx_http_request_t *r); 


其 中 ， 有 参数 ngx_http_request_t*r， 这 个 请 求 的 信息 都 可 以 从 Ir 中 

获得 。 这 样 可 以 定义 一 个 方法 void func(ngx_http_request_t*r)， 在 Nginx 
接收 完 包 体 时 调用 它 ， 男 外 ， 后 续 的 流程 也 都 会 写 在 这 个 方法 中 ， 例 

如 : 


void ngx_http_mytest_body_handler(ngx_http_redquest t *r) 


@ 注意 “ngx_http_mytest_body_handler 的 返回 类 型 是 void ，， 
Nginx 不 会 根据 返回 值 做 一 些 收尾 工作 ， 因 此 ， 我 们 在 该 方法 里 处 理 完 
请 求 时 必须 要 主动 调用 ngx_http_finalize_request 方 法 来 结束 请 求 。 


接收 包 体 时 可 以 这 样 写 


ngx_int_t rc = ngx_http_read client_request_body(r, 
ngx_http ee body_handler ) ， 
if (rc >= NGX_HTTP_SPECIAL RESPONSE) { 
return rc; 


} 
return NGX_DONE; 


Nginx 异 步 接收 HTTP 请 求 的 包 体 的 内 容 将 在 11.8 节 中 详 述 。 


如 采 不 想 处 理 请 求 中 的 包 体 ， 那 么 可 以 调用 
ngx_http_discard_request body 方法 将 接收 目 客 户 端的 HTTP 包 体 丢 弃 
挥 。 例 如 : 


ngx_int_t rc = ngx_http_discard_ request body(r); 
if (rc != NGX_OK) { 
return rc; 


} 


ngx_http_discard_request_body 只 是 丢弃 包 体 ， 不 处 理 包 体 不 就 行 
了 吗 ? 何必 还 要 调用 ngx_http_discard_request_body 方 法 呢 ? 其 实 这 


步 非 常 有 意义 ， 因 为 有 些 客户 端 可 能 会 一 直 试 图 发 送 包 体 ， 而 如 果 
HTTP 模 块 不 接收 发 来 的 TCP 流 ， 有 可 能 造成 客户 端 发 送 超时 。 


接收 完 请 求 的 包 体 后 ， 可 以 在 r->request_body->temp_file->file 中 
获取 临时 文件 (假定 将 r->request_body_in_file_only 标 志 位 设 为 1， 那 就 
一 定 可 以 在 这 个 变量 获取 到 包 体 。 更 复 洒 的 接收 包 体 的 方式 本 市 暂 不 
讨论 ) 。 人 le 是 一 个 ngx_file_t 类 型 ， 在 3.8 市 会 详细 介绍 它 的 用 法 。 这 
里 ， 我 们 可 以 从 r->request_body->temp_file->file.name 中 获取 Nginx 接 收 
到 的 请 求 包 体 所 在 文件 的 名 称 (包括 路 径 ) 


3.7 ”发 送 啊 应 


请 求 处 理 完 毕 后 ， 需 要 向 用 户 发 送 HITP 响 应 ， 告 知客 户 端 Nginx 
的 执行 结果 。HITP 响 应 主要 包括 响应 行 、 响 应 头 部 、 包 体 三 部 分 。 发 
送 HTTP 了 响应 时 需要 执行 发 送 HTTP 头 部 〈 发 送 HTTP 头 部 时 也 会 发 送 响 
应 行 ) 和 发 送 HTTP 包 体 两 步 操 作 。 本 节 将 以 发 送 经 典 的 “Hello 
World” 为 例 来 说 明 如 何 发 送 啊 应 。 


3.7.1 发 送 HTTP 头 部 


下 面 看 一 下 HTTP 框 架 提供 的 发 送 HTTP 头 部 的 方法 ， 如 下 所 示 。 


ngx_int_t ngx_http_send header(ngx_http_request t *r); 


调用 ngx_http_send_header 时 把 ngx_http_request_t 对 象 传 给 它 即 
可 ， 而 ngx_http_send_header 的 返回 值 是 多 样 的 ， 在 本 和 中 ， 可 以 认为 
返回 NGX_ERROR 或 返回 值 大 于 0 就 表示 不 正常 ， 例 如 : 


ngx_int_t rc = ngx_http_send_header(r); 

If (rc == NGX_ERROR || rc > NGX_OK || r->header_only) { 
return rc; 

} 


下 面 介 绍 设置 啊 应 中 的 HITP 头 部 的 过 程 。 


如 同 headers_in，ngx_http_request_t 也 有 一 个 headers_out 成 员 ， 用 
来 设置 响应 中 的 HTTP 头 部 ， 如 下 所 示 。 


struct ngx_http_request_Ss { 


ngx_http_headers_in_t headers_in,; 
ngx_http_headers out_t headers_out; 


}; 


只 要 指定 headers_out 中 的 成 员 ， 就 可 以 在 调用 
ngx_http_send_header 时 正确 地 把 HTTP 头 部 发 出 。 下 面 介绍 headers_onut 


的 结构 类 型 ngx_http_headers_out_t。 


typedef struct { 
// 待 发 送 的 


HTTP 头 部 链表 ， 与 


headers_in 中 的 


headers 成 员 类 似 


ngx_1list_t headers ， 


/响应 中 的 状态 值 ， 如 


200 表 示 成 功 。 这 里 可 以 使 


3.6.1 节 中 介绍 过 的 各 个 宏 ， 如 


NGX_HTTP_OK */ 
ngx_uint_t status; 
// 响应 的 状态 行 ， 如 “ 
HTTP/1.1 201 CREATED” 
ngx_str_t status_line; 
/* 以 下 成 员 (包括 


ngx_table_elt_t) 都 是 


RFC1616 规 范 中 定义 的 


HTTP 头 部 ， 设 置 后 ， 


ngx_http_header_filter_module 过 滤 模 块 可 以 把 它们 加 到 待 发 送 的 网 络 包 中 


ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table_ elt_t 
ngx_table_elt 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 
ngx_table elt_t 


*server,; 

xdate 
*content_length; 
*content_encoding; 
*location,; 
*refresh; 
*last_modified; 
*content_range; 
*accept_ranges,; 
*www_authenticate; 


ngx_table elt_t *expires,; 
ngx_table elt_t *etag; 

ngx_str_t *override_charset,; 
/* 可 以 调 


ngx_http_set_content_type(r) 方 法 帮助 我 们 设置 


Content -Type 头 部 ， 这 个 方法 会 根据 


URI 中 的 文件 扩展 名 并 对 应 着 


mime ,type 来 设置 


Content -Type 值 


*/ 
size_t content_type_len; 
ngx_str_t content_type; 
ngx_str_t charset; 
u_char *content_type_lowcase; 


ngx_uint_t 
ngx_array_t 
/* 在 这 里 指定 过 


content_type_hash; 
cache_control; 


content_length_n 后 ， 不 用 再 次 到 

ngx_table elt_t *content length 中 设置 响应 长 度 

*/ 
off_t content_length_n; 
time_t date_time; 
time_t last_modified_time; 


} ngx_http_headers out_t; 


在 癌 headers 链 表 中 添加 和 目 定义 的 HTTP 头 部 时 ， 可 以 参考 3.2.3 闻 
中 ngx_list_push 的 使 用 方法 。 这 里 有 一 个 简单 的 例子 ， 如 下 所 示 。 


ngx_table elt t* h = ngx_list push(&r->headers _ out.headers); 
if (h == NULL) { 
return NGX_ERROR,; 


} 
h->hash = 1; 

h->key. iene = sizeof("TestHead") - 1; 
h->key.data = (u_char *) rn 
h->value.len = sizeof("TestValue") - 
h->value.data = (u_char *) i 2 


这 样 将 会 在 啊 应 中 新 增 一 行 HITP 头 部 : 


TestHead: TestValue\r\n 


如 果 发 送 的 是 一 个 不 侣 有 HTTP 包 体 的 响应 ， 这 时 就 可 以 直接 结束 
请 求 了 (例如 ， 在 ngx_http_mytest_handler 方 法 中 ， 直 接 在 
ngx_http_send_header 方 法 执行 后 将 其 返回 值 return 即 可 ) 。 


@ 注意 “ngx_http_send_header 方 法 会 首先 调用 所 有 的 HTTP 过 滤 
模块 共同 处 理 headers_out 中 定义 的 HTTP 阿 应 头 部 ， 全 部 处 理 完毕 后 才 
会 序列 化 为 TCP 字 符 流 发 送 到 客户 端 ， 相 关 流 程 可 参见 11.9.1 节 。 


3.7.2 ”将 内 存 中 的 字符 串 作 为 包 体 发 送 


调用 ngx_http_output_filter 方 法 即 可 同 客 户 端 发 送 HTTP 啊 应 包 
体 ， 下面 查看 一 下 此 方法 的 原型 ， 如 下 所 示 。 


ngx_int_t ngx_http_output_filter(ngx_http_request t *r, ngx_chain t *in); 


ngx_http_output_filter 的 返回 值 在 mytest 例 子 中 不 需要 处 理 ， 通 过 
在 ngx_http_mytest_handler 方 法 中 返回 的 方式 传递 给 
ngx_http_finalize_request 即 可 。ngx_chain_t 结 构 已 经 在 3.2.6 节 中 介绍 
过 ， 它 仅 用 于 容纳 ngx_buf t 缓 冲 区 ， 所 以 需要 先 了 解 一 下 如 何 使 用 
ngx_buf t 分 配 内 存 。 下 面 介绍 Nginx 的 内 存 池 是 如 何 分 配 内 存 的 。 


为 了 减少 内 存 碎片 的 数量 ， 并 通过 统一 管理 来 减少 代码 中 出 现 内 
存 泄 漏 的 可 能 性 ，Nginx 设 计 了 ngx_pool t 内 存 池 数据 结构 。 本 章 我 们 
不 会 深入 分 析 内 存 池 的 实现 ， 只 关注 内 存 池 的 用 法 。 在 
ngx_http_mytest_handler 处 理 方法 传 来 的 ngx_http_request_t 对 和 象 中 就 有 
这 个 请 求 的 内 存 池 管 理 对 象 ， 我 们 对 内 存 池 的 操作 都 可 以 基于 它 来 进 
行 ， 这 样 ， 在 这 个 请 求 结束 的 时 候 ， 内 存 池 分 配 的 内 存 也 都 会 被 释 


A 


struct ngx_http_request _s { 


ngx_pool _t *pool; 


ss 


实际 上 ， 在 r 中 可 以 获得 许多 内 存 池 对 象 ， 这 些 内 存 池 的 大 小 、 意 
义 及 生存 期 各 不 相同 。 第 3 部 分 会 涉及 许多 内 存 池 ， 本 章 使 用 r>pool 内 
存 池 即 可 。 有 了 ngx_pool_ t 对 象 后 ， 可 以 从 内 存 池 中 分 配 内 存 。 例 
如 ， 下 面 这 个 基本 的 申请 分 配 内 存 的 方法 : 


void *ngx_palloc(ngx_pool t *pool, size t size); 


其 中 ，ngx_palloc 范 数 将 会 从 pool 内 存 池 中 分 配 到 size 字 市 的 内 
存 ， 并 返回 这 段 内 存 的 起 始 地 址 。 如 果 返 回 NULL 空 指针 ， 则 表示 分 
配 失 败 。 还 有 一 个 封装 了 ngx_palloc 的 函数 ngx_pcalloc， 它 多 做 了 一 件 
事 ， 就 是 把 ngx_palloc 申 请 到 的 内 存 块 全 部 置 为 0， 昌 然 ， 多 数 情况 下 
更 适合 用 ngx_pcalloc 来 分 配 内 存 。 


假如 要 分 配 一 个 ngx_buf t 结 构 ， 可 以 这 样 做 : 


ngx_buf_t* b = ngx_pcalloc(r->pool, sizeof(ngx_buf_t)); 


这 样 ，ngx_buf_t 中 的 成 员 指 同 的 内 存 仍 然 可 以 继续 分 配 ， 例 如 : 


b->start = (u_char*)ngx_pcalloc(r->pool, 128); 
b->pos = b->start,; 

b->last = b->start,; 

b->end = b->last + 128; 

b->temporary = 1; 


实际 上 ，Nginx 还 封装 了 一 个 生成 ngx_buf t 的 人 简便 方法 ， 它 完全 
等 价 于 上 面 的 6 行 语句 ， 如 下 所 示 。 


ngx_buf t *b = ngx_create temp_buf(r->pool, 128); 


分 配 完 内 存 后 ， 可 以 向 这 段 内 存 写 入 数据 。 当 写 完 数据 后 ， 要 让 
b->last 指 针 指向 数据 的 末尾 ， 如 果 b->last 与 b->pos 相 等 ， 那 么 HTTP 框 


发 送 一 个 字 市 的 包 体 的 。 


湛 
fi 
= 
办 


最 后 ， 把 上 面 的 ngx_buf_t*b 用 ngx_chain_t 传 给 
ngx_http_output_filter 方 法 就 可 以 发 送 HTTP 响 应 的 包 体内 容 了 。 例 
如 : 


ngx_chain_t out; 

out.buf = b; 

out.next = NULL; 

return ngx_http_output_filter(r, &out); 


人 @@ 注音 “在 向 用 户 发 送 响应 包 体 时 ， 必 须 牢记 Nginx 是 全 异步 的 
服务 器 ， 也 就 是 说 ， 不 可 以 在 进程 的 栈 里 分 配 内 存 并 将 其 作为 包 体 改 
送 。 当 一 直 ngx_http_output_filter 方 法 返回 时 ， 可 能 由 于 TCP 连 接 上 的 
缓冲 区 还 不 可 写 ， 所 以 导致 bgx_buf {缓冲 区 指向 的 内 存 还 没有 发 送 ， 
可 这 时 方法 返回 已 把 控制 权 交 给 Nginx 了 ， 又 会 导致 栈 里 的 内 存 被 释 
放 ， 最 后 就 会 造成 内 存 越界 错误 。 因 此 ， 在 发 送 响应 包 体 时 ， 尽 量 将 
ngx_buf t 中 的 pos 指 针 指向 从 内 存 池 里 分 配 的 内 存 。 


3.7.3 ”经典 的 “Hello World” 示 例 


下 面 以 经 典 的 返回 “Hello World” 为 例 来 编写 一 个 最 小 的 HTTP 处 理 
模块 ， 以 此 介绍 完整 的 ngx_http_mytest_handler 处 理 方法 。 


static ngx_int_t ngx_http_mytest_handler(ngx_http_request _t *r) 


// 必须 是 


GET 或 者 


HEAD 方 法 ， 否 则 返 世 


405 Not Allowed 
if (!(r->method & (NGX_HTTP_GET|NGX_HTTP_HEAD))) { 
return NGX_HTTP_NOT_ALLOWED,; 


} 

// 丢弃 请 求 中 的 包 体 

ngx_int_t rc = ngx_http_discard_ request_ body(r); 
if (rc != NGX_OK) { 


return rc; 


/* 设 置 返回 的 


中 


Content -Type。 注 ; 


ngx_str_t 有 一 个 很 方便 的 初始 化 宏 


ngx_string， 它 可 以 把 
ngx_str_t 的 
data 和 


len 成 员 都 设置 好 


7/ 
ngx_str_t type = ngx_string("text/plain"); 
// 返回 的 包 体内 容 


ngx_str_t response = ngx_string("Hello World!"); 
// 设置 返回 状态 码 


r->headers_out.status = NGX_HTTP_OK; 
// 响应 包 是 有 包 体 内 容 的 ， 需 要 设置 


Content-Length 长 度 


r->headers_out.content_length_n = response.1en,; 
// 设置 


Content-Type 
r->headers_out.content_type = type; 


// 发 送 
HTTP 头 部 
rc = ngx_http_send_header(r); 
if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) 


return rc; 


} 
// 构造 


ngx_buf_t 结 构 体 准备 发 送 包 体 


ngx_buf 七 *b， 
b = ngx_create temp_buf(r->pool, response.1en); 
if (b == NULL) { 
return NGX_HTTP_INTERNAL_ SERVER_ERROR, 
} 
// 将 


Hello World 复 制 到 


UD 


ngx_buf_t 指 向 的 内 存 


ngx_memcpy(b->pos, response.data, response,.1en); 
// 注意 ,一 定 要 设置 好 


last 指 针 


b->last = b->pos + response.1en; 
// 声明 这 是 最 后 一 块 缓冲 区 


b->last_buf = 1; 
// 构造 发 送 时 的 


ngx_chain_t 结 构 体 
ngx_chain_t out; 
// 赋值 
ngx_buf_t 


out.buf = b; 
// 设 


next 为 


NULL 
out.next = NULL; 
/* 最 后 一 步 为 发 送 包 体 ， 发 送 结束 后 


HTTP 框 架 会 调用 


ngx_http_finalize_request 方 法 结束 请 求 
*y 


} 


return ngx_http_output_filter(r, &out); 


3.8 ”将 磁盘 文件 作为 包 体 发 送 


上 文 讨 论 了 如 何 将 内 存 中 的 数据 作为 包 体 发 送 给 客户 端 ， 而 在 发 
送 文件 时 完全 可 以 先 把 文件 读 取 到 内 存 中 再 癌 用 户 发 送 数据 ， 但 是 这 
样 做 会 有 两 个 缺点 : 


为 了 不 阻塞 Nginx， 每 次 只 能 读 取 并 发 送 磁 盘 中 的 少量 数据 ， 需 
要 反复 持续 多 次 。 


:Linux 上 高 效 的 sendfile 系 统 调 用 不 需要 先 把 磁盘 中 的 数据 读 取 到 
用 户 态 内 存 再 发 送 到 网 络 中 。 


当然 ，Nginx 已 经 封 逆 好 了 多 种 接口 ， 以 便 将 磁盘 或 者 缓存 中 的 文 
件 发 送 给 用 户 。 


3.8.1 如 何 发 送 磁盘 中 的 文件 


发 送 文件 时 使 用 的 是 3.7 节 中 所 介绍 的 接口 。 例 如 : 


ngx_chain_t out 

out.buf = b; 

out.next = NULL; 

return ngx_http_output_filter(r, &out); 


两 者 不 同 的 地 方 在 于 如 何 设置 ngx_buf t 缓 神 区 。 在 3.2.5 节 中 介绍 
过 ，ngx_buf_t 有 一 个 标志 位 in_fle， 将 in_file 置 为 1 就 表示 这 次 
ngx_buf t 绥 冲 区 发 送 的 是 文件 而 不 是 内 存 。 调 用 ngx_http_output_filter 
后 ， 铬 Nginx 检 测 到 in_file 为 1， 将 会 从 ngx_buf t 绥 冲 区 中 的 身 e 成 员 处 
获取 实际 的 文件 。file 的 类 型 是 ngx_file t， 下 面 看 一 下 ngx_file_t 的 结 
构 。 


typedef struct ngx_file s ngx_file t; 
struct ngx_file s { 
// 文件 句柄 描述 符 


ngx_fd t fd; 
// 文件 名 称 


ngx_str_t name 
// 文件 大 小 等 资源 信息 ， 实 际 就 是 


Linux 系 统 定义 的 


stat 结 构 


ngx_file_info_t info,; 
/* 该 偏 移 量 告 诉 


Nginx 现 在 处 理 到 文件 何 处 了 ， 一 般 不 用 设置 它 ， 


Nginx 框 架 会 根据 当前 发 送 状态 设置 它 


* 
off_t offset ， 
// 当前 文件 系统 偏 移 量 ， 一 般 不 用 设置 它 ， 同 样 


Nginx 框 架设 


off_t sys_offset,; 
// 日 志 对 象 ， 相 关 的 日 志 会 输出 到 


10g 指 定 的 日 志文 件 中 


ngx_log_t *1og 
// 目前 未 使 


unsigned valid_ info:1; 


// 与 配置 文件 中 的 


directio 配 置 项 相对 应 ， 在 发 送 大 文件 时 可 以 设 为 


工 
unsigned directio:1; 


}; 


fd 是 打开 文件 的 句柄 描述 符 ， 打 开 文 件 这 一 步 需要 用 户 上 自己 来 
做 。Nginx 人 簿 单 封 装 了 一 个 宏 用 来 代替 open 系 统 的 调用 ， 如 下 所 示 。 


#define ngx_open_file(name, mode, create, access) \\ 
open((const char *) name, mode|create, access) 


实际 上 ，ngx_open_file 与 open 方 法 的 区 别 不 大 ，ngx_open_file 返 回 
的 是 Linux 系 统 的 文件 句柄 。 对 于 打开 文件 的 标志 位 ，Nginx 也 定义 了 
以 下 几 个 安 来 加 以 封装 。 


#define NGX_FILE_RDONLY 0_RDONLY 

#define NGX_FILE WRONLY 0_WRONLY 

#define NGX_FILE_ RDWR O_RDWR 

#define NGX_FILE_CREATE_OR_OPEN O_CREAT 
#define NGX_FILE OPEN 0 

#define NGX_FILE _ TRUNCATE O_CREAT|O_TRUNC 
#define NGX_FILE APPEND 0_WRONLY|0_APPEND 
#define NGX_FILE NONBLOCK 0_NONBLOCK 
#define NGX_FILE_ DEFAULT_ACCESS 0644 
#define NGX_FILE OWNER ACCESS 0600 


因此 ， 在 打开 文件 时 只 需要 把 文件 路 径 传 递 给 name 人 参数 ， 并 把 打 
开 方 式 传递 给 mode、create、access 参 数 即 可 。 例 如 : 


ngx_buf_t *b,; 

b = ngx_palloc(r->pool, sizeof(ngx_buf_t)); 

u_char* filename = (u_char*)"/tmp/test.txt",; 

b->in_file = 1; 

b->file = ngx_pcalloc(r->pool, sizeof(ngx_file t)); 

b->file->fd = ngx_open_file(filename, NGX_FILE RDONLY|NGX_FILE_ NONBLOCK, 
NGX_FILE_OPEN, 0); 


b->file->1og = r->connection->10g; 
b->file->name.data = filename,; 
b->file->name.len = strlen(filename); 
if (b->file->fd <= 0) 

{ 


return NGX_HTTP_NOT_FOUND ， 


到 这 里 其 实 还 没有 结束 ， 还 需要 告知 Nginx 文 件 的 大 小 ， 包 括 设置 
coortegh ee eh 
file_last。 实 际 上 ， 通 过 ngx_file_t 结 构 里 ngx_file_info_t 类 型 的 info 变 量 
就 可 以 获取 文件 信息 : 


typedef struct stat ngx_file info _t; 


Nginx 不 只 对 stat 数 据 结构 做 了 封闭， 对 于 由 操作 系统 中 获取 文件 
信息 的 stat 方 法 ，Nginx 也 使 用 一 个 安 进 行 了 简单 的 封装 ， 如 下 所 示 : 


#define ngx_file_ info(file, sb) stat((const char *) file, sb) 


因此 ， 获 取 文 件 信息 时 可 以 先 这 样 写 


if (ngx_file info(filename, &b->file->info) == NGX_FILE_ERROR) { 
return NGX_HTTP_INTERNAL_SERVER_ERROR ， 
} 


之 后 必须 要 设置 Content-Length 头 部 : 


r->headers_out.,content_Jlength_n = b->file->info.st_size， 


还 需要 设置 ngx_buf {t 绥 ; 中 区 的 fle_pos 和 file_last: 


b->file_pos = 0; 
b->file last = b->file->info.st_ size,; 


这 里 是 告诉 Nginx 从 文件 的 亿 e_pos 偏 移 量 开始 发 送 文 件 ， 一 直到 
达 file_last 偏 移 量 处 截止 。 


@@ 注意 当 磁 盘 中 有 大 量 的 小 文件 时 ， 会 占用 Linux 文 件 系统 
过 多 的 inode 结 构 ， 这 时 ， 成 熟 的 解决 方案 会 把 许多 小 文件 合并 成 一 个 
大 文件 。 在 这 种 情况 下 ， 当 有 需要 时 ， 只 要 把 上 面 的 file_pos 和 fne last 
设置 为 合适 的 偏 移 量 ， 就 可 以 只 发 送 合并 大 文件 中 的 某 一 块 内 容 ( 原 
来 的 小 文件 ， 这 样 就 可 以 大 幅 降 低 小 文件 数量 。 


3.8.2 ”清理 文件 句 棉 


Nginx 会 异步 地 将 整个 文件 高 效 地 发 送 给 用 户 ， 但 是 我 们 必须 要 求 
HTTP 框 架 在 响应 发 送 完 毕 后 关闭 已 经 打开 的 文件 句柄 ， 否 则 将 会 出 现 
句柄 泄露 问题 。 设 置 清 理 文件 句柄 也 很 简单 ， 只 需要 定义 一 个 
ngx_pool_cleanup_t 结 构 体 (这 是 最 简单 的 方法 ，HTTP 框 架 还 提供 了 
其 他 方式 ， 在 请 求 结束 时 回调 各 个 HTTP 模 块 的 cleanup 方 法 ， 将 在 第 
11 草 介绍 ) ， 将 我 们 刚 得 到 的 文件 句柄 等 信息 赋 给 它 ， 并 将 Nginx 提 供 


的 ngx_pool_cleanup_file 函 数 设置 到 它 的 handler 回 调 方法 中 即 可 。 首 先 
介绍 一 下 ngx_pool_cleanup_t 结 构 体 。 
typedef struct ngx_pool cleanup_s ngx_pool cleanup_t; 


struct ngx_pool _ cleanup_s 


// 执行 实际 清理 资源 工作 的 回调 方法 


ngx_pool_cleanup_pt handler; 
// handler 回 调 方 法 需要 的 参数 


void *data,; 
a = 


ngx_pool_cleanup_t 清 理 对 象 ， 如 果 没 有 ， 需 置 为 


NULL 
| ngx_pool_ cleanup_t *next; 
设置 好 handler 和 data 成 员 吏 有 可 能 要 求 HTTP 框 架 在 请 求 结束 前 传 
入 data 成 员 回 调 handler 方 法 。 接 着 ， 介 绍 一 下 专用 于 关闭 文件 句柄 的 


ngX_pool_cleanup_file 方 法 。 


void ngx_pool_cleanup_file(void *data) 
ngx_pool cleanup_file t *c = data,; 
ngx_log_debug1(NGX_LOG_ DEBUG ALLOC, c->lo0g, 0, "file cleanup: fd:%d",c->fd); 
if (ngx_close file(c->fd) == NGX_FILE ERROR) { 
ngx_log_error(NGX_ LOG ALERT, c->lo0g, ngx_errno, 
ngx_close_file n " \"%s\" failed", c->name); 


ngx_pool_cleanup_file 的 作用 是 把 文件 句柄 关闭 。 从 上 面 的 实现 中 
可 以 看 出 ，ngx_pool_cleanup_file 方 法 需要 一 个 ngx_pool]_cleanup_file_t 


类 型 的 参数 ， 那 么 ， 如 何 提供 这 个 参数 呢 ? 在 ngx_pool_cleanup_t 结 构 


体 的 data 成 员 上 赋值 即 可 。 下 面 介绍 一 下 ngx_pool_cleanup_file_{t 的 结 
构 。 


typedef Struct 区 
// 文件 句柄 


ngx_fd t fd; 
// 文件 名 称 


u_char *name 
// 日 志 对 象 


ngx_log_t *1og ， 
} ngx_pool_cleanup_file _t; 


可 以 看 到 ，ngx_pool_cleanup_file_t 中 的 对 象 在 ngx_buf 缓冲 区 的 
file 结 构 体 中 都 出 现 过 了 ， 意 义 也 是 相同 的 。 对 于 file 结 构 体 ， 我 们 在 
内 存 池 中 已 经 为 它 分 配 过 内 存 ， 只 有 在 请 求 结束 时 才 会 释放 ， 因 此 ， 
这 里 简单 地 引用 fe 里 的 成 员 即 可 。 清 理 文件 句 柄 的 完整 代码 如 下 。 


ngx_pool cleanup_t* cln = ngx_pool cleanup_add(r->pool, 
sizeof(ngx_pool cleanup_file t)); 
if (cln == NULL) { 

return NGX_ERROR; 


cln->handler = ngx_pool cleanup_file; 
ngx_pool cleanup_file t *clnf = cln->data,; 
clnf->fd = b->file->fd; 

clnf->name = b->file->name.data; 

Clnf->1og = 『->pool1L->1o0g 


ngx_pool_cleanup_add 用 于 告诉 HTTP 框 染 ， 在 请 求 结束 时 调用 cIn 
的 handler 方 法 清理 资源 。 


至 此 ，HTTP 模 块 已 经 可 以 同 客户 端 发 送 文件 了 。 下 面 介绍 一 下 如 
何 文 持 多 线程 下 载 与 断 点 续 传 。 


3.8.3 ” 文 持 用 户 多 线程 下 载 和 断 点 续 传 


RFC2616 规 范 中 定义 了 range 协 议 ， 它 给 出 了 一 种 规则 使 得 客户 端 
可 以 在 一 次 请 求 中 只 下 载 完 整 文件 的 某 一 部 分 ， 这 样 殉 可 文 持 客户 端 
在 开局 多 个 线程 的 同时 下 载 一 份 文件 ， 其 中 每 个 线程 仅 下 载 文件 的 一 
部 分 ， 最 后 组 成 一 个 完整 的 文件 。range 也 支持 断 点 续 传 ， 只 要 客户 端 
记录 了 上 次 中 断 时 已 经 下 载 部 分 的 文件 偏 移 量 ， 束 可 以 要 求 服务 器 从 
断 扩 处 发 送 文 件 之 后 的 内 容 。 


Nginx 对 range 协 议 的 文 持 非常 好 ， 因 为 range 协 议 主 要 增加 了 一 些 
HTTP 头 部 处 理 流程 ， 以 及 发 送 文件 时 的 偏 移 量 处 理 。 在 第 1 章 中 曾 说 
过 ，Nginx 设 计 了 HTTP 过 滤 模 块 ， 每 一 个 请 求 可 以 由 许多 个 HTTP 过 滤 
模块 处 理 ， 而 http_range_header filter 模 块 就 是 用 来 处 理 HTTP 请 求 头 部 
range 部 分 的 ， 它 会 解析 客户 端 请 求 中 的 range 头 部 ， 最 后 告知 在 发 送 
HTTP 响 应 包 体 时 将 会 调用 到 的 ngx_http_range_body_filter_module 模 
块 ， 该 模块 会 按照 range 协 议 修改 指向 文件 的 ngx_buf t 绥 冲 区 中 的 
file_pos 和 file_last 成 员 ， 以 此 实现 仅 发 送 一 个 文件 的 部 分 内 容 到 客户 


端 。 


其 实 ， 支 持 range 协 议 对 我 们 来 说 很 答 单 ， 只 需要 在 发 送 前 设置 
ngx_http_request_t 的 成 员 allow_ranges 变 量 为 1 即 可 ， 之 后 的 工作 都 会 
由 HTTP 框 架 完 成 。 例 如 : 


r->allow_ranges = 1; 


这 样 ， 我 们 束 文 择 了 多 线程 下 载 和 断 点 续 传 功能 。 


3.9 用 C++ 语言 编写 HTTP 模 块 


Nginx 及 其 官方 模块 都 是 由 C 语 言 开 发 的 ， 那 么 能 不 能 使 用 C++ 语 
言 来 开发 Nginx 模 块 呢 ? C 语 言 是 面 问 过 程 的 编程 语言 ，C++ 则 征 面 癌 
对 象 的 编程 语言 ， 面 癌 对 象 与 面 问 过 程 的 优 劣 这 里 暂且 不 论 ， 存 在 即 
合理 。 当 我 们 由 于 各 种 原因 需要 使 用 C++ 语言 实现 一 个 Nginx 模 块 时 

(例如 ， 某 个 子 功能 是 用 C++ 语言 写成 ， 或 者 开发 团队 对 C++ 语言 更 
熟练 ， 又 或 者 束 是 喜欢 使 用 C++ 语言 ) ， 尽 管 Nginx 本 吴 并 没有 提供 相 
应 的 方法 文 持 这 样 做 ， 但 由 于 C 语 言 与 C++ 语言 的 近亲 特性 ， 我 们 还 走 
可 以 比较 容易 达成 此 目的 的 。 


目 先 需要 弄 清 楚 相 关 解 决 方案 的 设计 思路 。 


:不 要 试图 用 C++ 编 译 器 (如 G++) 来 编译 Nginx 的 官方 代码 ， 这 会 
带 来 大 量 的 不 可 控 错误 。 正 确 的 做 法 是 仍然 用 C 编 译 器 来 编译 Nginx 官 
方 提供 的 各 模块 ， 而 用 C++ 编译 器 来 编译 用 C++ 语言 开发 的 模块 ， 最 
后 利用 C++ 向 前 兼容 C 语 言 的 特性 ， 使 用 C++ 编译 器 把 所 有 的 目标 文件 
链接 起 来 〈 包 括 C 编 译 器 由 Nginx 官 方 模块 生成 的 目标 文件 和 C++ 编译 
器 由 第 三 方 模块 生成 的 目标 文件 ) ， 这 样 才 可 以 正确 地 生成 二 进 制 文 
件 Nginx。 


-保证 C++ 编译 的 Nginx 模 块 与 C 编 译 的 Nginx 模 块 互 相 适 应 。 所 谓 
互相 适应 就 是 C++ 模块 要 能 够 调用 Nginx 框 架 提供 的 C 语 言 方法 ， 而 
Nginx 的 HTTP 框 架 也 要 能 够 正常 地 回调 C++ 模 块 中 的 方法 去 处 理 请 
求 。 这 一 点 用 C++ 提 供 的 extern“C” 特 性 即 可 实现 。 


下 面 详 述 如 何 实现 上 述 两 点 内 容 。 


3.9.1 编译 方式 的 修改 


Nginx 的 configure 脚 本 没有 对 C++ 语言 编译 模块 提供 支持 ， 因 此 ， 
修改 编译 方式 束 有 以 下 两 种 思路 : 


1) 修改 configure 相 关 的 脚本 。 
2) 修改 configure 执 行 完毕 后 生成 的 Makefile 文 件 。 


我 们 推荐 使 用 第 2 种 方法 ， 因 为 Nginx 的 一 个 优点 是 具备 大 量 的 第 
三 方 模 块 ， 这 些 模块 都 是 基于 官方 的 configure 脚 本 而 写 的 ， 擅 自修 改 
configure 脚 本 会 导致 我 们 的 Nginx 无 法 使 用 第 三 方 模块 。 


修改 Makefile 其 实 是 很 简单 的 。 首 先 我 们 根据 3.3.2 节 介绍 的 方式 
来 执行 configure 脚 本 ， 之 后 会 生成 obj%Makefile 文 件 ， 此 时 只 需要 修改 
这 个 文件 的 3 处 即 可 实现 C++ 模块 。 这 里 还 是 以 mytest 模 块 为 例 ， 代 码 
如 下 。 


CC = gcc 
CXX = g++ 


CFLAGS = -pipe -0 -W -Wall -Wpointer-arith -wno-unused-parameter -Wunused - 
function -wunused-variable -Wunused-value -Werror -9g 
CPP = gcc -E 


LINK = $(CXX).. 


objs/addon/httpmodule/ngx_http_mytest module.o: $(ADDON_DEPS) \ 
../Ssample/httpmodule/ngx_http_mytest_ module.c 
$(CXX) -c $(CFLAGS) $(ALL_INCS) \ 
-0 objs/addon/httpmodule/ngx_http_mytest_ module.o \ 
../Ssample/httpmodule/ngx_http_ mytest_ module.cpp... 


下 面 解释 一 下 上 述 代码 中 修改 的 地 方 。 


在 Makefile 文 件 首 部 新 增 了 一 行 CXX=g++， 即 添加 了 C++ 编译 


口 日 


五 计 © 


-把 链接 方式 LINK=$(CC) 改 为 了 LINK=$(CXX)， 表 示 用 C++ 编 译 
名 做 最 后 的 链接 。 


-把 模块 的 编译 方式 修改 为 C++ 编译 右 。 如 采 我 们 只 有 一 个 C++ 源 
文件 ， 则 只 要 修改 一 处 ， 但 如 果 有 多 个 C++ 源 文 件 ， 则 每 个 地 方 都 需 
要 修改 。 修 改 方式 是 把 $(CC) 改 为 $S(CCXX)。 


这 样 ， 编 译 方式 即 修改 完毕 。 修 改 源 文件 后 不 要 轻易 执行 
configure 脚 本 ， 否 则 会 覆盖 已 经 修改 过 的 Makefile。 建 议 将 修改 过 的 
Makefile 文 件 进行 备份 ， 避 免 每 次 执行 configure 后 重新 修改 Makefile 。 


@ 注意 ”确保 在 操作 系统 上 已 经 安装 了 C++ 编译 器 。 请 参照 


1.3.2 世 中 的 方式 安装 gcc-c++ 编 译 器 。 


3.9.2 ”程序 中 的 符号 转换 


C 语 言 与 C++ 语言 最 大 的 不 同 在 于 编译 后 的 符号 有 差别 《C++ 为 了 
文 持 多 种 面向 对 象 特性 ， 如 重 载 、 类 等 ， 编 译 后 的 方法 名 与 C 语 言 完 
全 不 同 ) ， 这 可 以 通过 C++ 语 言 提供 的 exterm“C”{} 来 实现 符号 的 互相 
识别 。 也 束 是 说 ， 在 C++ 语 言 开发 的 模块 中 ，include 包 含 的 Nginx 官 方 
头 文 件 都 需要 使 用 extern“C” 括 起 来 。 例 如 : 


extern "CcC" { 
#include <ngx_config.h> 
#include <ngx_core.h> 
#include <ngx_http.h> 

} 


这 样 束 可 以 正常 地 调用 Nginx 的 各 种 方法 了 。 


另外 ， 对 于 希望 Nginx 框 架 回 调 的 类 似 于 ngx_http_mytest_ handler 
这 样 的 方法 也 需要 放 在 extern“C” 中 。 


3.10 ”小 结 


本 章 讲述 了 如 何 开发 一 个 基本 的 HTTP 模 块 ， 这 里 除了 获取 请 求 的 
包 体 外 没有 涉及 异步 处 理 问题 。 通 过 本 章 的 学 习 ， 读 者 应 该 可 以 轻松 
地 编写 一 个 简单 的 HTTP 模 块 了 ， 既 可 以 获取 到 用 户 请 求 中 的 任何 信 
轧 ， 也 可 以 发 送 任意 的 响应 给 用 户 。 当 然 ， 处 理 方法 必须 是 快速 、 无 
阻塞 的 ， 因 为 Nginx 在 调用 例子 中 的 ngx_http_mytest_ handler 方 法 时 是 
阻塞 了 整个 Nginx 进 程 的 ， 所 以 ngx_http_mytest_ handler 或 类 似 的 处 理 
方法 中 是 不 能 有 耗 时 很 长 的 操作 的 。 


第 4 章 ”配置 、error 日 志和 请 求 上 下 文 


在 开发 功能 灵活 的 Nginx 模 块 时 ， 需 要 从 配置 文件 中 获取 特定 的 信 
思 ， 不 过 ， 不 需要 再 编写 一 套 读 取 配 置 的 系统 ，Nginx 已 经 为 用 户 提 供 
了 强大 的 配置 项 解析 机 制 ， 同 时 它 还 文 持 “-s reload” 命 令 一 一 在 不 重启 
服务 的 情况 下 可 使 配置 生效 。4.1 节 会 回顾 第 2 革 中 http 配 置 项 的 一 些 特 
点 ，4.2 太 中 会 全 面 讨 论 如 何 使 用 http 配 置 项 ， 包 括 使 用 Nginx 预 设 的 解 
析 方 法 (可 以 少 写 许多 代码 ) 或 者 自 定义 配置 项 的 解析 方式 ， 如 果 读 
者 对 其 中 较 复 杂 的 配置 块 藤 套 关 系 有 疑问 ， 在 4.3 世 中 会 从 HTTP 框 契 
的 实现 机 制 上 解释 http 配 置 项 的 模型 。 


开发 复杂 的 Nginx 模 块 时 ， 如 何 定 位 代码 上 的 问题 是 必须 考虑 的 前 
是 条 件 ， 此 时 输出 各 种 日 志 束 显得 很 关键 了 ，4.4 中 会 讨论 Nginx 为 
用 户 准 备 好 的 输出 日 志方 法 。 


编写 全 异步 的 HTTP 模 块 时 ， 必 须要 有 上 下 文 来 维持 一 个 请 求 的 必 
要 信息 ， 在 4.5 记 中， 首先 探讨 请 求 的 上 下 文 与 全 异步 实现 的 Nginx 服 
务 之 间 的 关系 ， 以 及 如 何 使 用 HTTP 上 下 文 ， 然 后 简单 描述 HTTP 框 架 
征 如 何 管理 请 求 的 上 下 文 结构 体 的 。 


4.1 ”http 配 置 项 的 使 用 场景 


在 第 2 章 中 通过 多 样 化 修改 nginx.conf 文 件 中 的 配置 项 ， 实 现 了 复 
杂 的 Web 服 务 器 功能 。 其 中 ，http{..} 内 的 配置 项 最 为 复杂 ， 在 http 配 
置 块 内 还 有 server 块 、location 块 等 ， 同 一 个 配置 项 可 以 同时 出 现在 多 
个 http 块 、server 块 或 location 块 内 。 


那么 ， 如 何 解析 这 样 的 配置 项 昵 ? 在 第 3 章 中 的 mytest 例 子 中 ， 又 
是 怎样 获取 nginx.conf 中 的 配置 的 呢 ? 当 同 一 个 配置 在 http 块 、server 
块 、location 块 中 同时 出 现时 ， 应 当选 择 哪 一 个 块 下 的 配置 呢 ? 当 多 个 
不 同 URI 表 达 陈 下 的 location 都 配置 了 mytest 文 个 配置 项 ， 然 而 后 面 的 
参数 值 却 不 同时 ，Nginx 是 如 何 处 理 的 呢 ? 这 些 殴 是 本 章 将 要 回答 的 问 


题 。 


我 们 先 来 看 一 个 例子 ， 有 一 个 配置 项 test_str， 它 在 多 个 块 内 都 出 
现 了 ， 如 下 所 示 * 


http { 
test_str main; 
server { 
listen 80; 
test_str server80,; 
location /urli { 
mytest; 
test_str loci; 


} 

location /url2 { 
mytest; 
test_str loc2; 


} 


server { 
listen 8080; 
test_str Server8080 
location /url3 { 
mytest; 
test_str loc3; 


} 


在 上 面 的 配置 文件 中 ，test_str 这 个 配置 项 在 http 块 内 出 现 的 值 为 
main， 在 监听 80 端 口 的 server 块 内 test_str 值 为 server80， 该 server 抉 内 有 
两 个 location 都 是 由 第 3 章 中 定义 的 mytest 模 块 处 理 的 ， 而 且 每 个 
location 中 又 重新 设置 了 test_str 的 值 ， 分 别 为 1oc1 和 ]loc2。 在 这 之 后 又 
定义 了 监听 8080 病 口 的 server 块 ， 并 重 定 义 test_str 的 值 为 server8080， 

这 个 server 抉 内 定义 的 一 个 location 也 是 由 mytest 模 块 处 理 的， 而 且 这 个 
location 内 再 次 重 定义 了 test_str 的 值 为 1oc3。 (事实 上 不 只 是 例子 中 的 
server 块 可 以 嵌 套 location 块 ，location 块 之 间 还 可 以 继续 舱 套 ， 这 样 
test_str 的 值 就 更 复杂 了 ， 上 例 中 没有 出 现 location 中 进一步 反复 舱 套 
location 的 场景 。 在 4.3.3 节 讨论 HTTP 框 架 如 何 合并 配置 项 时 涉及 了 


location 块 的 反复 骨 套 问题 ， 请 读者 注意 。) 


在 这 段 很 短 的 配置 中 ，mytest 模 块 将 会 处 理 两 个 监听 端口 上 建立 
的 TCP 连 接 ， 以 及 3 种 HTTP 请 求 ， 请 求 的 URL 分 别 对 应 
着 /url1、Amrl2、/url3。 假 设 mytest 模 块 必 须 取 出 test_str 配 置 项 的 参数 ， 
可 是 在 以 上 的 例子 中 test_str 出 现 了 6 个 不 同 的 参数 值 ， 分 别 为 main、 


server80、server8080、loc1、loc2、1loc3， 那 么 在 mytest 模 块 中 我 们 取 
到 的 test_str 值 以 哪 一 个 为 准 呢 ? 


事实 上 ，Nginx 的 设计 是 非常 灵活 的 (实际 上 这 是 第 10 章 将 要 介绍 
的 HTTP 框 架设 计 的 ) ， 它 在 每 一 个 http 块 、server 块 或 location 块 下 ， 
都 会 生成 独立 的 数据 结构 来 存放 配置 项 。 因 此 ， 我 们 允许 当 用 户 访问 
的 请 求 不 同时 (如 请 求 的 URL 分 别 是 /urll1、/Wurl2、/url3) ， 配 置 项 
test_str 可 以 具有 不 同 的 值 。 那 么 ， 当 请 求 是 /url1 时 ，test_str 的 值 应 当 
是 location 块 下 的 loc1， 还 是 这 个 location 所 属 的 server 块 下 的 server80， 
又 或 者 是 其 所 属 http 块 下 的 值 main 呢 ?完全 由 mytest 模 块 自己 决定 ， 我 
们 可 以 定义 这 个 行为 。 下面 在 4.2 节 中 将 说 明 如 何 灵活 地 使 用 配置 项 ， 
在 4.3 节 中 将 探讨 Nginx 实 际 上 是 如 何 实现 http 配 置 功能 的 。 


4.2 ”怎样 使 用 http 配 置 


事实 上 ， 在 第 3 章 中 已 经 使 用 过 mytest 配 置 项 ， 只 不 过 当时 mytest 配 
置 项 是 没有 值 的 ， 只 是 用 来 标识 当 location 块 内 出 现 mytest 配 置 项 时 就 
启用 mytest 模 块 ， 从 而 处 理 匹 配 该 location 表 达 式 的 用 户 请 求 。 本 章 将 
由 易 到 难 来 阐述 HTTP 模 块 是 怎样 获得 感 兴趣 的 配置 项 的 。 


处 理 http 配 置 项 可 以 分 为 下 面 4 个 步 又: 
1) 创建 数据 结构 用 于 存储 配置 项 对 应 的 参数 。 
2) 设 定 配 置 项 在 nginx.conf 中 出 现时 的 限制 条 件 与 回调 方法 。 


3) 实现 第 2 步 中 的 回调 方法 ， 或 者 使 用 Nginx 和 框架 预 设 的 14 个 回调 


4) 合并 不 同 级 别 的 配置 块 中 出 现 的 同名 配置 项 。 


不 过 ， 这 4 个 步骤 如 何 与 Nginx 有 机 地 结合 起 来 呢 ? 就 是 通过 第 3 章 
中 介绍 过 的 两 个 数据 结构 ngx_http_module_t 和 ngx_command_t， 它 们 都 
是 定义 一 个 HTTP 模 块 时 不 可 或 缺 的 部 分 


4.2.1 分配 用 于 保存 配置 参数 的 数据 结构 


首先 需要 创建 一 个 结构 体 ， 其 中 包含 了 所 有 我 们 感 兴趣 的 参数 。 
为 了 说 明 14 种 预 设 配置 项 的 解析 方法 ， 我 们 将 在 这 个 结构 体 中 定义 14 
个 成 员 ， 存 储 感 兴趣 的 配置 项 参数 。 例 如 : 


typedef struct { 


ngx_str_t my_str; 
ngx_int_t my_num; 
ngx_flag_t my_flag; 
size_t my_size; 
ngx_array_t* my_str_array; 
ngx_array_t* my_keyval; 
off_t my_off; 
ngx_msec_t my_msec; 
time_t my_sec; 
ngx_bufs_t my_bufs; 
ngx_uint_t my_enum_seq; 
ngx_uint_t my_bitmask; 
ngx_uint_t my_access 
ngx_path_t* my_path; 


} ngx_http_mytest_conf_t; 


ngx_http_mytest_conf_t 中 的 14 个 成 员 存 储 的 配置 项 都 不 相同 ， 读 者 
可 和 暂时 名 略 上 面 ngx_http_mytest_conf _t 结 构 中 一 些 没 见 过 的 Nginx 数 据 
结构 ， 这 些 将 在 4.2.3 节 中 介绍 。 


为 什么 要 这 么 严格 地 用 一 个 结构 体 来 存储 配置 项 的 参数 值 ， 而 不 
是 随意 地 定义 儿 个 全 局 变量 来 存储 它们 呢 ? 这 就 要 回 到 4.1 市 中 例子 的 
使 用 场景 了 ， 多 个 location 块 (或 者 http 块 、server 块 ;中 的 相同 配置 项 
是 允许 同时 生效 的 ， 也 就 是 说 ， 我 们 刚刚 定义 的 ngx_http_mytest_conf t 
结构 必须 在 Nginx 的 内 存 中 保存 许多 份 。 事 实 上 ，HTTP 框 架 在 解析 
nginx.conf 文 件 时 只 要 遇 到 http{}、server{f} 或 者 location{} 配 置 块 束 会 立 
刻 分 配 一 个 新 的 ngx_http_mytest_conf t 结 构 体 。 因 此 ，HTTP 模 块 感 兴 


趣 的 配置 项 需要 统一 地 使 用 一 个 struct 结 构 体 来 保存 (否则 HTTP 框 架 无 
法 管理 ， 如 果 nginx.conf 文 件 中 在 http{} 下 有 和 多 个 server{} 或 者 
location{}， 那 么 这 个 struct 结 构 体 在 Nginx 进 程 中 就 会 存在 多 份 实例 。 


Nginx 怎 样 管 理 我 们 目 定义 的 存储 配置 的 结构 体 
ngX_http_mytest_conf t 呢 ? 很 简单 ， 通 过 第 3 章 中 兽 经 提 到 的 
ngx_http_module_t 中 的 回调 方法 。 下 面 回顾 一 下 ngx_http_module_t 的 害 
义 。 

typedef struct { 
ngx_int_t (*preconfiguration)(ngx_conf_t *cf)， 
ngx_int_t (*postconfiguration)(ngx_conf_t *cf); 


void * 
char * 


*create_ main_conf)(ngx_conf_t *cf); 
*init_main_conf)(ngx_conf_t *cf, void *conf); 

void *(*create_srv_conf)(ngx_conf_t *cf); 

char *(*merge_srv_conf)(ngx_conf_t *cf, void *prev, void *conf); 

void *(*create_ loc conf)(ngx_conf_t *cf); 

char *(*merge_ loc conf)(ngx_conf_t *cf, void *prev, void *conf); 
} ngx_http_module_t; 


一 一 一 一 一 


其 中 ，create_main_conf、create_SrV_conf、create_loc_conf 这 3 个 回 
调 方法 负责 把 我 们 分 配 的 用 于 保存 配置 项 的 结构 体 传 递 给 HTTP 框架 。 
下 面 解释 一 下 为 什么 不 是 定义 1 个 而 是 定义 3 个 回调 方法 。 


HTTP 框 架 定 义 了 3 个 级 别 的 配置 main、srv、loc， 分 别 表示 直接 出 
现在 http{}、server{}、location{} 块 内 的 配置 项 。 当 nginx.conf 中 出 现 
http{} 时 ，HTTP 框 染 会 接管 配置 文件 中 http{} 块 内 的 配置 项 解析 ， 之 后 
的 流程 可 以 由 4.3.1 市 中 的 图 4-1 来 了 解 。 当 巡 到 http{...} 配 置 块 时 ， 
HTTP 框 架 会 调用 所 有 HTTP 模 块 可 能 实现 的 create_main_conf 、 


create_SrV_conf、create_loc_conf 方 法 生成 存储 main 级 别 配 置 参数 的 结构 
体 ; 在 遇 到 server{..} 块 时 会 再 次 调用 所 有 HTTP 模 块 的 
create_SrV_conf、create_loc_conf 回 调 方法 生成 存储 srv 级 别 配 置 参数 的 
结构 体 ; 在 遇 到 location{.…} 时 则 会 再 次 调用 create_loc_conf 回 调 方法 生 
成 存储 loc 级 别 配置 参数 的 结构 体 。 因 此 ， 实 现 这 3 个 回调 方法 的 意义 是 
不 同 的 ， 例 如 ， 对 于 mytest 模 块 来 说 ， 在 http{} 块 内 只 会 调用 1 次 
create_main_conf， 而 create_loc_conf 可 能 会 被 调用 许多 次 ， 也 就 是 有 许 
多 个 由 create_ loc_conf 生 成 的 结构 体 。 


普通 的 HITP 模 块 往 往 只 实现 create_loc_conf 回 调 方法 ， 因 为 它们 只 
关注 匹配 某 种 URL 的 请 求 。 我 们 的 mytest 例 子 也 是 这 样 实 现 的 ， 这 里 实 
现 create_loc_conf 的 是 ngx_http_mytest_create_loc_conf 方 法 ， 如 下 所 


修 ° 


static void* ngx_http_mytest_create_ loc conf(ngx_conf_t *cf) 


ngx_http_mytest_conf_t *mycf; 
mycf = (ngx_http_mytest_conf t *)ngx_pcalloc(cf->pool, 
Sizeof(ngx_http_mytest_conf 七 ) ) ， 
if (mycf == NULL) 区 
return NULL; 
} 


mycf->my_flag = NGX_CONF_UNSET; 
mycf->my_num = NGX_CONF_UNSET ， 
mycf->my_str_array = NGX_CONF_UNSET_PTR; 
mycf->my_keyval = NULL; 

mycf->my_off = NGX_CONF_UNSET ， 


mycf->my_msec = NGX_CONF_UNSET_MSEC ， 
mycf->my_sec = NGX_CONF_UNSET ， 
mycf->my_size = NGX_CONF_UNSET_SIZE; 
return mycf,; 


上 述 代 码 中 对 一 些 配 置 参 数 设置 了 初始 值 ， 这 是 为 了 14 个 预 设 方 
法 准备 的 ， 下 面 会 解释 为 什么 要 这 样 赋值 。 


4.2.2” 设 定 配 置 项 的 解析 方式 


下 面 详细 介绍 在 读 取 HTTP 配 置 时 是 如 何 使 用 ngx_command_t 结 构 
的 ， 首 先 回顾 一 下 第 3 章 中 曾经 提 到 过 的 定义 ， 再 详细 介绍 每 个 成 员 的 
意义 。 


struct ngx_command_s { 
ngx_str_t name; 
ngx_uint_t type; 
char *(*set)(ngx_conf_t *cf, ngx_command_t *cmd, void *conf); 
ngx_uint_t conf; 
ngx_uint_t offset,; 
void *post; 


(1) ngx_str_ tname 
其 中 ，name 是 配置 项 名 称 ， 如 4.1 市 例子 中 的 “test_str”。 
(2) ngx_uint ttype 


其 中 ，type 决 定 这 个 配置 项 可 以 在 哪些 块 (如 http、server、 
location、 计 、upstream 块 等 ) 中 出 现 ， 以 及 可 以 携带 的 参数 类 型 和 个 数 
等 。 表 4-1 列 出 了 设置 http 配 置 项 时 type 可 以 取 的 值 。 注 意 ，type 可 以 同 
时 取 表 4-1 中 的 多 个 值 ， 各 值 之 间 用 | 符号 连接 ， 例 如 ，type 可 以 取 值 为 


NGX_HITIP MAIN CONFINGX _ HTTP_SRV_CONFINGX _ HTTP LOC 
CONFINGX_ CONF_TAKE1° 


表 4-1 ngx_command_t 结 构 体 中 type 成 员 的 取 值 及 其 意义 


ETEEE 吉文 
- 般 由 NGX_CORE _ MODULE 类 型 的 核心 模块 使 用 ， 

仅 与 下 面 的 NGX_MAIN_CONFE 同时 设置 ， 表 示 模 块 需要 

解析 不 属于 任何 全 内 的 全 局 配置 项 。 它 实际 上 会 指定 set 

方法 里 的 第 3 个 参数 conf 的 值 ， 使 之 指向 每 个 模块 解析 全 

局 配置 项 的 配 辣 结构 体 " 

目前 未 使 用 ， 设 置 与 否 均 无 意义 

配置 项 可 以 出 现在 全 局 配置 中 ， 即 不 属于 任何 {} 配置 块 

配置 项 可 以 出 现在 events {} 块 内 

配置 项 可 以 出 现在 mail ff 块 或 者 imap 人 块 内 


配置 项 可 以 出 现在 server {} 块 内 ， 然 而 该 server 和 块 必 


机关 大 可 以 中 现在 WP ( 志 


ee ee server 由 块 内 。 然 而 该 server 块 必须 

:哪些 i ) 4 了 sa 人 时 : 
eg | dn We location 各 块 内 ， 然 而 该 location 块 
~ ee upstream {} 块 内 。 然 而 该 upstream 块 


配置 项 可 以 出 现在 location 块 内 的 让 中 块 中 。 目前 仅 有 
rewrite 模块 会 使 用 ,该 让 抉 必须 属于 http {} 块 


配置 项 可 以 出 现在 limit_except 们 抉 内 ， 然 而 该 Timit_ 
except 块 必须 属于 http 全 块 


NGX_CONF NOARGS 配置 项 不 携带 任何 参数 


配置 项 必须 携带 1 个 参数 
配置 项 必须 携带 2 个 参数 
配置 项 必须 携带 3 个 参数 
配置 项 必须 携带 4 个 参数 
i 配置 项 必须 携带 5 个 参数 
了 > 配置 项 必须 携带 6 个 参数 
配置 项 必须 携带 7 个 参数 
配置 项 可 以 携带 1 个 参数 或 2 个 参数 
配置 项 可 以 携带 1 个 参数 或 3 个 参数 
配置 项 可 以 携带 2 个 参数 或 3 个 参数 
配置 项 可 以 携带 1! ~ 3 个 参数 
配置 项 可 以 携带 1 ~ 4 个 参数 


处 理 配 置 项 时 获取 |NGX_DIRECT_CONF 
当前 配置 块 的 方式 


NGX_HTTP_LIF_ CONF 


NGX CONF ARGS NUMBER | 目前 未 使 用 ， 无 意义 


配置 项 定义 了 一 种 新 的 屿 块 。 例 如 ，http 、server、 
NGX CONF BLOCK location 等 配置 ， 它 们 的 type 都 必须 定义 为 NGX_CONF_ 
BLOCK 


NGX CONF ANY 不 验证 配置 项 携带 的 参数 个 数 


配置 项 携带 的 参数 只 能 是 1 个 ， 并 且 参 数 的 值 只 能 是 on 
NGX CONF FLAG ee 
全 六 或 者 off 


配置 项 携带 的 参数 个 数 必须 超过 1 个 
se 配置 项 携带 的 参数 个 数 必须 超过 2 个 
限制 配置 项 后 的 参 
数 出 现 的 形式 表示 当前 配置 项 可 以 出 现在 任意 块 中 (包括 不 属于 任何 
块 的 全 局 配置 )， 它 仅 用 于 配合 其 他 配置 项 使 用 。type 中 未 
加 NGX_CONF _ MULTI 时， 如 果 一 个 配置 项 出 现在 type 
成 员 未 标明 的 配置 块 中 ,那么 Nginx 会 认为 该 配置 项 非法 ， 
最 后 将 导致 Nginx 启动 失败 。 但 如 果 type 中 加 入 了 NGX 
NGX CONF MULTI CONF MULTI， 则 认为 该 配置 项 一 定 是 合法 的 ， 然 而 又 
会 有 两 种 不 同 的 结果 : 中 如 果 配 置 项 出 现在 type 指示 的 块 
中 ， 则 会 调用 set 方法 解析 配置 项 ; @ 如 果 配 置 项 没有 出 现 
在 type 指示 的 块 中 ， 则 不 对 该 配置 项 做 任何 处 理 。 因 此 ， 
NGX_CONF_MULTI 会 使 得 配置 项 出 现在 未 知 块 中 时 不 会 
出 错 。 目前， 还 没有 官方 模块 使 用 过 NGX_CONF_MULTI 


QD 每 个 进程 中 都 有 一 个 唯一 的 ngx_cycle_t 核 心 结构 体 ， 它 有 一 个 成 
员 conf_ctx 维 护 着 所 有 模块 的 配置 结构 体 ， 其 类 型 是 void**** 。conf_ctx 
意义 为 首先 指向 一 个 成 员 疆 为 指针 的 数组 ， 其 中 每 个 成 员 指 针 又 指向 
另外 一 个 成 员 丝 为 指针 的 数组 ， 第 2 个 子 数组 中 的 成 员 指 针 才 会 指向 各 
模块 生成 的 配置 结构 体 。 这 正 是 为 了 事件 模块 、http 模 块 、mail 模 块 而 
设计 的 ， 第 9、10 章 都 有 详 述 ， 这 有 利于 不 同 于 NGX_CORE_MODULE 
类 型 的 特定 模块 解析 配置 项 。 然 而 ，NGX_CORE_MODULE 类 型 的 核 
心 模块 解析 配置 项 时 ， 配 置 项 一 定 是 全 局 的 ， 不 会 从 属于 任何 {} 配 置 
块 的 ， 它 不 需要 上 述 这 种 双 数 组 设计 。 解 析 标 识 为 
NGX_DIRECT_CONF 类 型 的 配置 项 时 ， 会 把 void**** 类 型 的 conf_ctx 强 


制 转换 为 void**， 也 就 是 说 ， 此 时 ， 在 conf_ctx 指 向 的 指针 数组 中 ， 
个 成 员 指针 不 再 指向 其 他 数组 ， 直 接 指向 核心 模块 生成 的 配置 结构 
体 。 因 此 ，NGX_DIRECT_CONF 仅 由 NGX_CORE_MODULE 类 型 的 核 
心 模块 使 用 ， 而 且 配 置 项 只 应 该 出 现在 全 局 配置 中 。 


@@ 汪 阁 ”如 果 HTTP 模 块 中 定义 的 配置 项 在 nginx.conf 配 置 文件 中 
实际 出 现 的 位 置 和 参数 格式 与 type 的 意义 不 符 ， 那 么 Nginx 在 启动 时 会 
报错 。 


(3) char*(*set)(ngx_conf t*cf,ngx_command_t*cmd,void*conf) 


关于 set 回 调 方法 ， 在 第 3 章 中 处 理 mytest 配 置 项 时 已 经 使 用 过 ， 其 
中 mytest 配 置 项 是 不 带 参数 的 。 如 果 处 理 配置 项 ， 我 们 既 可 以 上 自己 实现 
一 个 回调 方法 来 处 理 配 置 项 〈4.2.4 节 中 会 举例 说 明 如 何 自 定义 回调 方 
法 ) ， 也 可 以 使 用 Nginx 预 设 的 14 个 解析 配置 项 方法 ， 这 会 少 写 许 多 代 
码 ， 表 4-2 列 出 了 这 些 预 设 的 解析 配置 项 方法 。 我 们 将 在 4.2.3 节 中 举例 
说 明 这 些 预 设 方法 的 使 用 方式 。 


表 4-2 ”了 预 设 的 14 个 配置 项 解析 方法 


预 设 方法 名 


ngx_conf set flag slot 


negx conf set str Slot 


ngx_conf set str array slot 


ngx_conf set keyval slot 


ngx_cont set num slot 


ngx_ conf set size Slot 


ngx_conf set_off slot 


ngx_conf set_ msee slot 


ngx_conf set _ sec slot 


ngx_conf set bufs siot 


行 为 

如 果 nginx.conf 文件 中 某 个 配置 项 的 参数 是 on 或 者 of { 即 希 望 配 置 项 表达 打 
开 或 者 关闭 某 个 功能 的 意思 )， 而 且 在 Nginx 模块 的 代码 中 使 用 ngx_flag_t 变量 来 
保存 这 个 配置 项 的 参数 ， 就 可 以 将 set 回调 方法 设 为 ngx_conf set flag_slot。 当 
nginx.conf 文件 中 参数 是 on 时 ， 代 码 中 的 ngx_flag_t 类 型 变量 将 设 为 1， 参数 为 
o 作 时 则 设 为 0 

如 果 配 置 项 后 只 有 1 个 参数 ,同时 在 代码 中 我 们 希望 用 ngx_str + 类 地 的 变量 来 
保存 这 个 配 署 项 的 参数 ， 则 可 以 使 用 ngx_conf _set_str_slot 方法 

如 果 这 个 配置 项 会 出 现 多 次 ， 每 个 配置 项 后 面 都 跟着 1 个 参数 ， 而 在 程序 中 我 
们 和 希望 仅 用 一 个 ngx_array 1 动态 数组 (用 法 见 7.3 节 ) 来 存储 所 有 的 参数 ， 且 数 
组 中 的 每 个 参数 都 以 ngx_str t 来 存储 ， 那 么 预 设 的 ngx_conf set_str_array_slot 方 
法 可 以 帮 有 我 们 做 到 

与 ngx_conf set_str_array_slot 类 似 ， 也 是 用 一 个 ngx_array t 数组 来 存储 所 有 
同名 配置 项 的 参数 。 只 是 每 个 配置 项 的 参数 不 再 只 是 1 个， 而 必须 是 两 个 ， 且 以 
“配置 项 名 关键 字 值 ;” 的 形式 出 现在 nginx.conf 文件 中 ， 同 时 ,ngx_conf set_ 
keyval slot 将 把 这 些 配置 项 转化 为 数组 ， 其 中 每 个 元 素 都 存储 着 key/value 键 值 对 

配置 项 后 必须 携带 1 个 参数 ， 且 只 能 是 数字 。 存 储 这 个 参数 的 变量 必 须 是 整 型 

配置 项 后 必须 携带 1 个 参数， 表示 空间 大 小 ， 可 以 是 一 个 数字 ， 这 时 表示 字 节 
数 ( Byte)。 如 果 数 字 后 跟着 k 或 者 K， 就 表示 Kilobyte，1KB=1024B ; 如 果 数 字 
后 跟着 m 或 者 M， 就 表示 Megabyte、1MB=1024KB。ngx_conf set_ size_slot 解析 
后 将 把 配置 项 后 的 参数 转化 成 以 字 节 数 为 单位 的 数字 

配置 项 后 必须 携带 1 个 参数 ， 表 示 空 间 上 的 偏 移 最 。 它 与 设置 的 参数 非常 类 似 ， 
其 参数 是 一 个 数字 时 表示 Byte， 也 可 以 在 后 面 加 单位 .但 与 ngx_conf set_size_ 
slot 不 同 的 是 ,数字 后 面 的 单位 不 仅 可 以 是 k 或 者 KK、m 或 者 M， 还 可 以 是 g 或 
者 G， 这 时 表示 Gigabyte，1GB=1024MB。ngx_conf set_off stot 解析 后 将 把 配置 
项 后 的 参数 转化 成 以 字 节 数 为 单位 的 数字 

配置 项 后 必须 携带 1 个 参数 ， 表 示 时 间 。 这 个 参数 可 以 在 数字 后 面 加 单位 ， 如 
果 单 位 为 s 或 者 没有 任何 单位 ， 那 么 这 个 数字 表示 秒 ; 如 果 单 位 为 m， 则 表示 
分 钟 ， lm=60s ; 如 果 单 位 为 hb、 则 表示 小 时 ，1h=60m ; 如 果 单 位 为 d4， 则 表示 
天 .1d=24h ; 如 果 单 位 为 w， 则 表示 周 ，1w=7d ; 如 果 单 位 为 M， 则 表示 月 ， 
1M=30d ;如 果 单 位 为 y， 则 表示 年 ，1y=365d。ngx_conf set_ masec slot 解析 后 将 
把 配置 项 后 的 参数 转化 成 以 毫秒 为 单位 的 数字 

与 ngx_conf set_msec_slot 非常 类 似 ， 唑 一 的 区 别 是 ngx_conf set_ msec slot 解 
析 后 将 把 配置 项 后 的 参数 转化 成 以 毫秒 为 单位 的 数字 ，、 而 ngx_conf set_ sec_slot 
解析 后 会 把 配置 项 后 的 参数 转化 成 以 秒 为 单位 的 数字 

配置 项 后 必须 携带 一 两 个 参数 ,第 1 个 参数 是 数字 ， 第 2 个 参数 表示 空间 大 小 。 
例如 ，*”gzip_buffers 4 8k;” (通常 用 来 表示 有 多 少 个 ngx_buf t+ 缓冲 区 )， 其 中 第 1 
个 参数 不 可 以 携带 任何 单位 ， 第 2 个 参数 不 带 任何 单位 时 表示 Byte， 如 果 以 k 或 
者 K 作为 单位 ， 则 表示 Kilobyte， 如 果 以 m 或 者 M 作为 单位 ， 则 表示 Megabyte。 
ngx_conf set_bufs_slot 解析 后 会 把 配置 项 后 的 两 个 参数 转化 成 ngx_bufs t 结构 体 
下 的 两 个 成 员 。 这 个 配置 项 对 应 于 Nginx 最 喜欢 用 的 多 缓冲 区 的 解决 方案 ( 如 接 
收 连 接 对 端 发 来 的 CP 流 ) 


预 设 方法 名 


ngx conf set enum _ slot 


ngx conf set_bitmask_ slot 


ngx conf set access slot 


ngx conf set path slot 


( 续 ) 
行 为 

配置 项 后 必须 携带 1 个 参数 ， 其 取 值 范围 必须 是 我 们 设 定 好 的 字符 串 之 一 (就 
像 C 语言 中 的 枚 举 一 样 )。 首 先 ， 我 们 要 用 nsgx_conf enum t 结构 定义 配置 项 的 取 
值 范 围 ， 并 设 定 每 个 值 对 应 的 序列 号 。 然 后 ，ngx_conf set_enum_slot 将 会 把 配置 
项 参数 转化 为 对 应 的 序列 号 

与 ngx_conf set_bitmask slot 类 似 ， 配 置 项 后 必须 携带 1 个 人 参数， 其 取 值 范围 必 
须 是 设 定好 的 字符 串 之 一 。 首 先 ， 我 们 要 用 ngx_conf bitmask t 结 构 定 义 配置 项 
的 取 值 范围 ， 并 设 定 每 个 值 对 应 的 比特 位 。 注 意 ， 每 个 值 所 对 应 的 比特 位 都 要 不 
同 。 然 后 ngx_conf set_bitmask _slot 将 会 把 配置 项 参数 转化 为 对 应 的 比特 位 

这 个 方法 用 于 设置 目录 或 者 文件 的 读 写 权限 。 配 置 项 后 可 以 携带 1 ~ 3 个 参数 ， 
可 以 是 如 下 形式 : user:rw group:rw all:rw。 注 意 ， 它 的 意义 与 Linux 上 文件 或 者 
目录 的 权限 意义 是 一 致 的 ,但 是 user/group/all 后 面 的 权限 只 可 以 设 为 rw ( 读 / 写 ) 
或 者 r (只 读 ), 不 可 以 有 其 他 任何 形式 ， 如 Ww 或 者 IX 等 ngx_conf set access_ 
slot 将 会 把 这 些 参数 转化 为 一 个 整 型 

这 个 方法 用 于 设置 路 径 ， 配 置 项 后 必须 携带 1 个 参数 ,表示 1 个 有 意义 的 路 径 


ngx_conf set_path_slot 将 会 把 参数 转化 为 ngx_path t 结构 


(4) ngx_uint_t conf 


conf 用 于 指示 配置 项 所 处 内 存 的 相对 偏 移 位 置 ， 仪 在 type 中 没有 设 
置 NGX_DIRECT_CONF 和 NGX_MAIN_CONF 时 才 会 生效 。 对 于 HTTP 
模块 ，conf 是 必须 要 设置 的 ， 它 的 取 值 范围 见 表 4-3。 


表 4-3 ”ngx_command_t 结 构 中 的 conf 成 员 在 HTTP 模 块 中 的 取 值 及 其 意 


conf 在 HTTP 模块 中 的 取 值 意 义 
NGX HTTP MAIN CONF_ OFFSET 使 用 create_main_conf 方 法 产生 的 结构 体 来 存储 解析 出 的 配置 项 参数 
NGX HTTP_SRV_CONF_ OFFSET 使 用 create_srv_conf 方 法 产生 的 结构 体 来 存储 解析 出 的 配置 项 参数 
NGX HTTP LOC CONF OFFSET 使 用 create_loc_conf 方 法 产生 的 结构 体 来 存储 解析 出 的 配置 项 参数 


为 什么 HTTP 模 块 一 定 要 设置 conf 的 值 呢 ? 因为 HTTP 框 架 可 以 使 用 
预 设 的 14 种 方法 自动 地 将 解析 出 的 配置 项 写 入 HTTP 模块 代码 定义 的 结 
构 体 中 ， 但 HTTP 模 块 中 可 能 会 定义 3 个 结构 体 ， 分 别 用 于 存储 main、 


SrV、1loc 级 别 的 配置 项 (对 应 于 create_main conf 、create_srv_conf 、 
create_loc_conf 方 法 创建 的 结构 体 ) ， 而 HTTP 框 染 自 动 解析 时 需要 知道 
应 把 解析 出 的 配置 项 值 写 入 哪个 结构 体 中 ， 这 将 由 conf 成 员 完 成 。 


此 ， 对 conf 的 设置 是 与 ngx_http_module_t 实 现 的 回调 方法 (在 
4.2.1 方 中 介绍 ) 相关 的 。 如 果 用 于 存储 这 个 配置 项 的 数据 结构 是 由 
create_main_conf 回 调 方法 完成 的 ， 那 么 必须 把 conf 设 置 为 
NGX_HTTP_MAIN_CONF_OFFSET。 同样， 如 果 这 个 配置 项 所 属 的 数 
据 结 构 是 由 create_srv_conf 回 调 方 法 完成 的 ， 那 么 必须 把 conf 设 置 为 
NGX_HTTP_SRV_CONF_OFFSET。 可 如 果 create_loc_conf 人 负责 生成 存 
储 这 个 配置 项 的 数据 结构 ， 就 得 将 conf 设 置 为 
NGX_HTTP LOC CONF_OFFSET。 


目前 ， 功 能 较为 简单 的 HITP 模 块 都 只 实现 了 create_ loc_conf 回 调 方 
法 ， 对 于 http{}、server{} 块 内 出 现 的 同名 配置 项 ， 都 是 并 入 某 个 
location{} 内 create_loc_conf 方 法 产生 的 结构 体 中 的 (在 4.2.5 节 中 会 详 壕 
如 何 合并 配置 项 。 当 我 们 希望 同时 出 现在 http{}、server{}、 
location{} 块 的 同名 配置 项 ， 在 HTTP 模 块 的 代码 中 保存 于 不 同 的 变量 中 
上 时， 就 需要 实现 create_main_conf 方 法 、create_srv_conf 方 法 产生 新 的 结 
构 体 ， 从 而 以 不 同 的 结构 体 独 立 保存 不 同 级别 的 配置 项 ， 而 不 是 全 首 
合并 到 某 个 location 下 create_loc_conf 方 法 生成 的 结构 体 中 。 


(5) ngx_uint t offset 


offset 表 示 当 前 配置 项 在 整个 存储 配置 项 的 结构 体 中 的 俩 移 位 置 
(以 字 亡 (Byte) 为 单位 ) 。 举 个 例子 ， 在 32 位 机 器 上 ，int ( 整 型 ) 
类 型 长 度 是 4 字 市 ， 那 么 看 下 面 这 个 数据 结构 : 


typedef struct { 
int a; 
int b; 
int c; 

} test_stru; 


如 果 要 处 理 的 配置 项 是 由 成 员 b 来 存储 参数 的 ， 那 么 这 时 b 相 对 于 
test_stru 的 偏 移 量 就 是 4;， 如 果 要 处 理 的 配置 项 由 成 员 c 来 存储 参数 ， 那 
人 这 时 c 相 对 于 test_stru 的 偏 移 量 就 是 8。 


实际 上 ， 这 种 计算 工作 不 用 用 户 自己 来 做 ， 使 用 offsetof 宏 即 可 实 
现 。 例 如 ， 在 上 例 中 取 b 的 偏 移 量 时 可 以 这 么 做 : 


offsetof(test_stru, b) 
其 中 ，offsetof 中 第 1 个 参数 是 存储 配置 项 的 结构 体 名 称 ， 第 2 个 参 


数 是 这 个 结构 体 中 的 变量 名 称 。offsetof 将 会 返回 这 个 变量 相对 于 结构 


体 的 仿 移 量 。 


© 提示 ”offsetof 这 个 宏 是 如 何 取得 成 员 相 对 结构 体 的 偏 移 量 的 
呢 ? 其实 很 简单 ， 它 的 实现 类 似 于 : #define offsetof(type,member) 
(size_t)&(((type*)0)->member)。 可 以 看 到 ，offsetof 将 0 地 址 转换 成 type 


结构 体 类 型 的 指针 ， 并 在 访问 member 成 员 时 取得 member 成 员 的 指针 ， 
这 个 指针 相对 于 0 地 址 来 说 目 然 束 古 成 员 相 对 于 结构 体 的 仿 移 量 了 。 


设置 offset 有 什么 作用 呢 ? 如 果 使 用 Nginx 预 设 的 解析 配置 项 方法 ， 
束 必 须 设置 offset， 这 样 Nginx 首 先 通过 conf 成 员 找到 应 该 用 哪个 结构 体 
来 存放 ， 然 后 通过 offset 成 员 找到 这 个 结构 体 中 的 相应 成 员 ， 以 便 存 放 
该 配置 。 如 果 有 是 和 目 定义 的 专用 配置 项 解析 方法 (只 解析 某 一 个 配置 
项 ) ， 则 可 以 不 设置 offset 的 值 。 读 者 可 以 通过 4.3.4 节 来 了 解 预 设 配 置 
项 解析 方法 是 如 何 使 用 offset 的 。 


(6) void*post 
post 指 针 有 许多 用 途 ， 从 它 被 设计 成 void* 束 可 以 看 出 。 


如 有 条目 定义 了 配置 项 的 回调 方法 ， 那 么 post 指 针 的 用 途 完 全 由 用 户 
来 定义 。 如 果 不 使 用 它 ， 那 么 随意 设 为 NULL 即 可 。 如 果 想 将 一 些 数据 
结构 或 者 方法 的 指针 传 过 来 ， 那 么 使 用 post 也 可 以 。 


如 有 宁 使 用 Nginx 预 设 的 配置 项 解析 方法 ， 就 需要 根据 这 些 预 设 方 法 
来 决定 post 的 使 用 方式 。 表 4-4 说 明了 post 相 对 于 14 个 预 设 方法 的 用 途 。 


表 4-4 ”ngx_command_t 结 构 中 post 的 取 值 及 其 意义 


post 的 使 用 方式 适用 的 预 设 配置 项 解析 方法 
ngx conf set flag slot 
ngx_conf set_str_slot 
ngx conf set str array_slot 
可 以 选择 是 否 实现 。 如 果 设 为 NULL， 则 表示 不 实现 ， 否 则 必须 实现 为 指向 | ngx_conf set_keyval_slot 
ngx_conf post t 结构 的 指针 。ngx_conf_post_t 中 包含 一 个 方法 指针 ， 表 示 在 解析 | ngx_conf set_num_slot 


当前 配置 项 完毕 后 ， 需 要 回调 这 个 方法 ngx conf set_size_slot 
ngx conf set off slot 
ngx conf set msec slot 
ngx conf set_sec slot 
指 回 ngx_conf enum t 数 组 ， 表 示 当 前 配置 项 的 参数 必须 设置 为 ngx_conf_ 
enum t 规定 的 值 (类 似 枚 举 )。 注 意 ， 使 用 ngx_conf set_enum slot 时 必须 设置 定 | ngx_conf set_enum slot 
义 1 个 ngx_conf_enum t 数 组， 并 将 post 成 员 指 问 该 数组 
指 问 ngx_conf bitmask t 数组 ， 表 示 当 前 配置 项 的 参数 必须 设置 为 ngx_conf 
bitmask t 规定 的 值 (类 似 枚 举 )。 注 意 ， 使 用 ngx_conf set_bitmask _ slot 时 必须 设 | ngx_conf set_bitmask slot 
置 定义 1 个 ngx_conf bitmask t 数组， 并 将 post 成员 指 向 该 数组 


ngx_conf set_bufs_slot 
无 任何 用 处 ngx_conf set path slot 


ngx conf set access slot 


可 以 看 到 ， 有 9 个 预 设 方法 在 使 用 时 post 是 可 以 设置 为 
ngx_conf post_t 结 构 体 来 使 用 的 ， 先 来 看 看 ngx_conf_ post t 的 定义 。 


typedef char *(*ngx_conf_post_handler_pt) (ngx_conf tt *cf， 
void *data, void *conf); 

typedef struct { 
ngx_conf_post_handler_pt post_handler; 

} ngx_conf_post_t; 


如 果 需 要 在 解析 完 配 置 项 〈 表 4-4 中 列 出 的 前 9 个 预 设 方法 ) 后 回调 
某 个 方法 ， 就 要 实现 上 面 的 ngx_conf_post_handler_pt， 并 将 包含 
post_handler 的 ngx_conf_post_t 结 构 体 传 给 post 指 针 。 


目前 ，ngx_conf_post_t 结 构 体 提供 的 这 个 功能 没有 官方 Nginx 模 块 
使 用 ， 因 为 它 限制 过 多 且 post 成 员 过 于 灵活 ， 一 般 完全 可 以 
init_main_conf 这 样 的 方法 统一 处 理解 析 完 的 配置 项 。 


4.2.3 ”使 用 14 种 预 设 方法 解析 配置 项 


本 世 将 以 举例 的 方式 说 明 如 何 使 用 这 14 种 Nginx 的 预 设 配置 项 解析 
方法 来 处 理 我 们 感 兴趣 的 配置 项 。 下 面 仍然 以 4.2.1 节 生成 的 配置 项 结 
构 体 ngx_http_mytest_conf_t 为 例 进 行 说 明 ， 其 中 会 尽量 把 type 成 员 的 多 
种 用 法 都 涵盖 到 。 


(1) ngx_conf set flag_slot 


假设 我 们 希望 在 nginx.conf 中 有 一 个 配置 项 的 名 称 为 test_flag， 它 的 
后 面 携带 1 个 参数 ， 这 个 参数 的 取 值 必须 是 on 或 者 off。 我 们 将 用 4.2.1 廊 
中 生成 的 ngx_http_mytest_conf t 结 构 体 中 的 以 下 成 员 来 保存 : 


ngx_flag_t my_flag; 
先 看 一 下 ngx_flag_t 的 定义 : 


typedef intptr_t ngx_flag_t; 


可 见 ，ngx_flag_t 与 ngx_int_t 整 型 是 相当 的 。 可 以 如 下 设置 
ngx_conf _set_flag _ slot 来 帮助 解析 test_flag 参 数 。 


static ngx_command t ngx_http_mytest commands[] = { 


{ ngx_string("test_flag"), 
NGX_HTTP_LOC_CONF| NGX_CONF_FLAG， 
ngx_conf_set_flag_slot, 


NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_flag), 
NULL }, 

ngx_null command 


上 上 段 代 码 表 示 ，test_flag 配 置 只 能 出 现在 location{...} 块 中 (更 多 的 
type 设 置 可 参见 表 4-1) 。 其 中 ，test_flag 配 置 项 的 参数 为 on 时 ， 
ngx_http_mytest_conf t 结 构 体 中 的 my_flag 会 设 为 1， 而 参数 为 off 时 
my_flag 会 设 为 0。 


er 注意 ”在 ngx_http_mytest_create_loc_conf 创 建 结 构 体 时 ， 如 果 
想 使 用 ngx_conf_set_flag_slot， 必 须 把 my_flag 初 始 化 为 
NGX_CONF_UNSET 宏 ， 世 就 是 4.2.1 闻 中 的 语句 “mycf- 
>test_flag=NGX_CONF_UNSET:”， 人 否则 ngx_conf_set_flag_slot 方 法 在 解 
析 时 会 报 “is duplicate” 错 误 。 


(2) ngx_conf set_str_slot 


假设 我 们 希望 在 nginx.conf 中 有 一 个 配置 项 的 名 称 为 test_str， 其 后 
的 参数 只 能 是 1 个 ， 我 们 将 用 ngx_http_mytest_conf t 结 构 体 中 的 以 下 成 


可 以 这 么 设置 ngx_conf_set_str_slot 来 实现 test_str 的 解析 ， 如 下 所 


static ngx_command t ngx_http_mytest commands[] = { 


{ ngx_string("test_str"), 
NGX_HTTP_MAIN_CONF |NGX_HTTP_SRV_CONF |NGX_HTTP_LOC_CONF| NGX_CONF_TAKE1， 
ngx_conf_set_str_slot, 
NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_str), 
NULL }, 
ngx_null_command 


‘ 


以 上 代码 表示 test_str 可 以 出 现在 http{...}、server{...} 或 者 
location{...} 块 内 ， 它 携 囊 的 1 个 参数 会 保存 在 my_str 中 。 例 如 ， 有 以 下 
配置 : 


location ... 


test_str apple,; 


那么 ，my_str 的 值 为 {len=5;data=“apple”;}。 
(3) ngx_ conf set str_array_slot 


如 果 硕 望 在 nginx.conf 中 有 多 个 同名 配置 项 ， 如 和 名称 是 
test_str_array， 那 么 每 个 配置 项 后 都 跟着 一 个 字符 串 参 数 。 这 些 同 名 配 
置 项 可 能 具有 多 个 不 同 的 参数 值 。 这 时 ， 可 以 使 用 
ngX_conf set_str_array_slot 预 设 方法 ， 它 将 会 把 所 有 的 参数 值 都 以 
ngx_str_t 的 类 型 放 到 ngx_array_t 队 列 容器 中 ， 如 下 所 示 。 


static ngx_command t ngx_http_mytest commands[] = { 


{ ngx_string("test_str_array"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1, 


ngx_conf_set_str_array_slot, 
NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_str_array), 
NULL }, 

ngx_null_command 


}; 


在 4.2.1 世 中 已 看 到 my_str_array 是 ngx_array_t* 类 型 的 。ngx_array_f 
数据 结构 的 使 用 方法 与 ngx_list_t 类 似 。 本 章 不 详细 讨论 ngx_array_t 容 
器 ， 感 兴趣 的 读者 可 以 直接 阅读 第 6 章 查看 ngx_array_t 的 使 用 特点 。 


上 面 代 码 中 的 test_str_array 配 置 项 也 只 能 出 现在 location{...} 块 内 。 
如 果 有 以 下 配置 : 


location ... 


test_str_array Content-Length; 
test_str_array Content-Encoding; 


} 


那么 ，my_str_array->nelts 的 值 将 是 2， 表 示 出 现 了 两 个 test_str_array 配 
置 项 。 而 且 ，my_str_array->elts 指 加 ngx_str_t 类 型 组 成 的 数组 ， 这 样 吏 
可 以 按 以 下 方式 访问 这 两 个 值 。 


ngx_str_t*pstr=mycf->my_str_array->elts,; 


于 是 ，pstr[0] 和 pstr[1] 可 以 取 到 参数 值 ， 分 别 是 
{len=14;data=“Content-Length”;} 和 {len=16;data=“Content-Encoding”;}。 
从 这 里 可 以 看 到 ， 当 处 理 HITP 头 部 这 样 的 配置 项 时 是 很 适合 使 用 
ngx_conf_set_str_array_slot 预 设 方法 的 。 


(4) ngx_conf set keyval slot 


ngx_conf_set_keyval_slot 人 与 ngx_conf_set_str_array_slot 韭 常 相似 ， 唯 
一 的 不 同 点 是 ngx_conf_set_str_array_slot 要 求 同 名 配置 项 后 的 参数 个 数 
是 1， 而 ngx_conf set_keyval_slot 则 要 求 配 置 项 后 的 参数 个 数 是 2， 分 别 
表示 key/value。 如果 用 ngx_array_t* 类 型 的 my_keyval 变 量 存储 以 
test_keyval 作 为 配置 名 的 参数 ， 则 必须 设置 NGX_CONF_TAKE2， 表 示 
test_keyval 后 跟 两 个 参数 。 例 如 : 


static ngx_command_t ngx_http_mytest _ commands[] = { 


{ ngx_string("test_keyval"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE2, 
ngx_conf_set_keyval_ slot, 
NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_keyval), 
NULL }, 

ngx_null_command 


如 果 nginx.conf 中 出 现 以 下 配置 项 : 


location ... 


test_keyval Content-Type image/png; 
test_keyval Content-Type image/gif; 
test_keyval Accept-Encoding gzip; 

} 


那么 ，ngx_array_t* 类 型 的 my_keyval 将 会 有 3 个 成 员 ， 每 个 成 员 的 类 型 
如 下 所 示 。 


typedef struct { 
ngx_str_t key; 


ngx_str_t value; 
} ngx_keyval tt， 


因此 ， 通 过 通 历 my_keyval 束 可 以 获取 3 个 成 员 ， 分 别 是 {<Content- 
Type”,“image/png”} ~、 {“Content-Type’”,“image/gif”} ~ {“Accept- 
Encoding”,“gzip”}。 例 如 ， 取 得 第 1 个 成 员 的 代码 如 下 。 


ngx_keyval_t* pkv = mycf->my_keyval->elts; 
ngx_log_error(NGX_LOG_ ALERT, r->connection->log, 0, 
"my_keyval key=%*s,value=%*s,", 
pkv[0].Kkey.1len,pkv[0].key.data, 
pkv[0] .value.1len,pkv[90].value.data); 


对 于 ngx_log_error 日 志 的 用 法 ， 将 会 在 4.4 广 评 细 说 明 。 


@ 注意 ”在 ngx_http_mytest_create_loc_conf 创 建 结构 体 时 ， 如 果 
想 使 用 ngx_conf_set_keyval_slot， 必 须 把 my_keyval 初 始 化 为 NULL 空 指 
针 ， 也 就 是 4.2.1T 中 的 语句 “mycf->my_keyval=NULL;”， 人 否则 
ngx_conf_set_keyval_slot 在 解析 时 会 报错 。 


(5) ngx_conf _ set num, slot 


dS 


ngx_conf set_num_slot 处 理 的 配置 项 必须 携 市 1 个 参数 ， 这 个 参数 
必须 是 数字 。 我 们 用 ngx_http_mytest_conf t 结 构 中 的 以 下 成 员 来 存储 这 
个 数字 参数 如 下 所 示 。 


ngx_int_t my_num; 


如 果 用 "test_num" 表 示 这 个 配置 项 名 称 ， 那 么 ngx_command_t 可 以 
写成 如 下 形式 。 


static ngx_command t ngx_http_mytest commands[] = { 


{ ngx_string("test_num"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1, 
ngx_conf_set_num_slot, 
NGX_HTTP_LOC_CONF_OFFSET， 
offsetof(ngx_http_mytest_conf_t, my_num), 
NULL }, 

ngx_null_command 


如 果 在 nginx.conf 中 有 test_num 10; 配 置 项 ， 那 么 my_num 变 量 就 会 
设置 为 10。 


er 注意 “在 ngx_http_mytest_create_loc_conf 创 建 结 构 体 时 ， 如 果 
想 使 用 ngx_conf_set_num_slot， 必 须 把 my_num 初 始 化 为 
NGX_CONF_UNSET 宏 ， 也 就 是 4.2.1 闻 中 的 语句 “mycf- 
>my_num=NGX_CONF_UNSET;”， 否 则 ngx_conf_set_num_slot 在 解析 
时 会 报错 。 


(6) ngx_conf set_ size slot 


如 果 希 望 配置 项 表达 的 作 义 是 空间 大 小 ， 那 么 用 
ngx_conf_set_size_slot 来 解析 配置 项 是 非常 合适 的 ， 因 为 
ngx_conf_set_size_slot 允 许配 置 项 的 参数 后 有 单位 ， 例 如 ，k 或 者 K 表 示 
Kilobyte，m 或 者 M 表 示 Megabyte。 用 ngx_http_mytest_conf _t 结 构 中 的 


size_t my_size; 来 存储 参数 ， 解 析 后 的 my_size 表 示 的 单位 是 字 广 。 例 
如 : 


static ngx_command_t ngx_http_mytest commands[] = { 


{ ngx_string("test_size"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1, 
ngx_conf_set_size_slot, 
NGX_HTTP_LOC_CONF_OFFSET， 
offsetof(ngx_http_mytest_conf_t, my_size), 
NULL }, 

ngx_null_command 


如 果 在 nginx.conf 中 配置 了 test_size 10k;， 那 么 my_size 将 会 设置 为 
10240。 如 果 配 置 为 test_size 10m;， 则 my_size 会 设置 为 10485760 。 


ngx_conf_set_size_slot 只 人 允许 配置 项 后 的 参数 携带 单位 k 或 者 K、m 
或 者 M， 不 允许 有 g 或 者 G 的 出 现 ， 这 与 ngx_conf_set_off_slot 是 不 同 
的 。 


er 注意 “在 ngx_http_mytest_create_loc_conf 创 建 结 构 体 时 ， 如 果 
想 使 用 ngx_conf _set_size_slot， 必 须 把 my_size 初 始 化 为 
NGX_CONF_UNSET_SIZE 宏 ， 也 就 是 4.2.1 世 中 的 语句 “mycf- 
>my_size=NGX_CONF_UNSET _SIZE;”， 人 否则 ngx_conf_set_size_slot 在 
解析 时 会 报错 。 


(7) ngx_conf set_off slot 


如 采 和 希望 配置 项 表达 的 含义 是 空间 的 偏 移 位 置 ， 那 么 可 以 使 用 
ngx_conf_set_off_slot 预 设 方法 。 事 实 上 ，ngx_conf_set_off_slot 与 
ngx_conf_set_size_slot 是 非常 相似 的 ， 最 大 的 区 别 是 
ngx_conf_set_off_slot 文 持 的 参数 单位 还 要 多 1 个 g 或 者 G， 表 示 
Gigabyte。 用 ngx_http_mytest_conf t 结 构 中 的 off_t my_off; 来 存储 参数 ， 
解析 后 的 my_off 表 示 的 偏 移 量 单位 古 字 市 。 例 如 : 


static ngx_command_t ngx_http_mytest commands[] = { 


{ ngx_string("test_off"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1, 
ngx_conf_set_off_slot, NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_off), 
NULL }, 

ngx_null_command 


如 果 在 nginx.conf 中 配置 了 test_off 1g;， 那 么 my_off 将 会 设置 为 
1073741824。 当 它 的 单位 为 k、K、m、M 时 ， 其 意义 与 


ngx_conf_set_size_slot 相 同 。 


@ 注意 ”在 ngx_http_mytest_create_loc_conf 创 建 结 构 体 村， 如果 
想 使 用 ngx_conf_set_off_slot， 必 须 把 my_off 初 始 化 为 
NGX_CONF_UNSET 宏 ， 也 就 是 4.2.1 广 中 的 语句 “mycf- 
>my_off=NGX_CONF_UNSET;”， 否 则 ngx_conf_set_off_slot 在 解析 时 会 
报错 。 


(8) ngx_conf set_ msec slot 


如 有 果 硕 望 配置 项 表达 的 含义 是 时 间 长 得， 那么 用 
ngx_conf _set_msec_slot 来 解析 配置 项 是 非常 合适 的 ， 因 为 它 文 持 非 党 
多 的 时 间 单 位 。 


用 ngx_http_mytest_conf t 结 构 中 的 ngx_msec_t my_msec; 来 存储 参 
数 ， 解 析 后 的 my_msec 表 示 的 时 间 单 位 是 双 秒 。 事 实 上 ，ngx_msec t 十 


一 个 无 符号 整 型 : 


typedef ngx_uint_t ngx_rbtree key_t; 
typedef ngx_rbtree key_t ngx_msec_t; 


ngx_conf_set_msec_slot 解 析 的 配置 项 也 只 能 携带 1 个 参数 。 例 如 : 


static ngx_command t ngx_http_mytest commands[] = { 


{ ngx_string("test_msec"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1, 
ngx_conf_set_msec_slot, NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_msec), 
NULL }, 

ngx_null_command 


如 果 在 nginx.conf 中 配置 了 test_msec 1d;， 那 么 my_msec 会 设置 为 1 
天 之 内 的 野 秒 数 ， 也 就 是 86400000。 


@ 注意 ”在 ngx_http_mytest_create_loc_conf 创 建 结 构 体 时 ， 如 果 
想 使 用 ngx_conf_set_msec_slot， 那 么 必须 把 my_msec 初 始 化 为 
NGX_CONF_UNSET_MSEC 安 ， 也 就 是 4.2.1 节 中 的 语句 “mycf- 


>my_msec=NGX_CONF_UNSET_MSEC;”， 人 否则 ngx_conf _set_msec_Sslot 
在 解析 时 会 报错 。 


(9) ngx_ conf set sec slot 


ngx_conf_set_sec_slot 与 ngx_conf_set_msec_slot 非 常 相 似 ， 只 是 
ngx_conf_set_sec_slot 在 用 ngx_http_mytest_conf _t 结 构 体 中 的 time_t 
my_sec; 来 存储 参数 时 ， 解 机 后 的 my_sec 表 示 的 时 间 单 位 是 秒 ， 而 


ngx_conf_set_msec_slot 为 坚 秒 。 


static ngx_command t ngx_http_mytest_commands[] = { 


{ ngx_string("test_sec"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1, 
ngx_conf_set_sec_slot, 
NGX_HTTP_LOC_CONF_OFFSET， 
offsetof(ngx_http_mytest_conf_t, my_sec), 
NULL }, 

ngx_null_command 


如 果 在 nginx.conf 中 配置 了 test_sec 1d;， 那 么 my_sec 会 设置 为 1 天 之 
内 的 秘 数 ， 也 束 定 86400。 


@ 注意 “在 ngx_http_mytest_create_ loc_conf 创 建 结 构 体 时 ， 如 果 
想 使 用 ngx_conf_set_sec_slot， 那 么 必须 把 my_sec 初 始 化 为 
NGX_CONF_UNSET 宏 ， 也 就 是 4.2.1 节 中 的 语句 “mycf- 
>my_sec=NGX_CONF_UNSET”， 人 否则 ngx_conf_set_sec_slot 在 解析 时 
会 报销 。 


(10) ngx_conf set_bufs_slot 


Nginx 中 许多 特有 的 数据 结构 都 会 用 到 两 个 概念 : 单个 ngx_buf t 绥 
存 区 的 空间 大 小 和 人 允许 的 缓存 区 个 数 。ngx_conf_set_bufs_slot 就 是 用 于 
设置 它 的 ， 它 要 求 配 置 项 后 必须 携带 两 个 参数 ， 第 1 个 参数 是 数字 ， 通 
常会 用 来 表示 缓存 区 的 个 数 ， 第 2 个 参数 表示 单个 缓存 区 的 空间 大 小 ， 
它 像 ngx_conf set_size_slot 中 的 参数 单位 一 样 ， 可 以 不 携带 单位 ， 也 可 
以 使 用 k 或 者 K、m 或 者 M 作 为 单位 ， 如 “gzip_buffers 48k;”。 我 们 用 
ngx_http_mytest_conf t 结 构 中 的 ngx_bufs_t my_bufs; 来 存储 参数 ， 
ngx_bufs_t (12.1.3 节 ngx_http_upstream_conf t 结 构 体 中 的 bufs 成 员 就 是 
应 用 ngx_bufs_t 配 置 的 一 个 非常 好 的 例子 ) 的 定义 很 简单 ， 如 下 所 示 。 


typedef struct { 
ngx_int_t num， 
size_t size; 

} ngx_bufs_t; 


ngx_conf_set_bufs_slot 解 析 后 会 把 配置 项 后 的 两 个 参数 转化 成 
ngx_bufs_t 结 构 下 的 两 个 成 员 num 和 size， 其 中 size 以 字 市 为 单位 。 例 
如 : 


static ngx_command_t ngx_http_mytest_commands[] = { 


{ ngx_string("test_bufs"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE2, 
ngx_conf_set_bufs_slot, NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_bufs), 


ngx_null_command 


如 果 在 nginx.conf 中 配置 为 test_bufs 41k;， 那 么 my_bufs 会 设置 为 
{4,1024}° 


(11) ngx_conf set_enum_slot 


ngx_conf_set_enum_slot 表 示 枚 举 配置 项 ， 也 就 是 说 ，Nginx 模 块 代 
码 中 将 会 指定 配置 项 的 参数 值 只 能 是 已 经 定义 好 的 ngx_conf_enum t 数 
组 中 name 字 符 串 中 的 一 个 。 先 看 看 ngx_conf _enum_t 的 定义 如 下 所 示 。 


typedef struct { 
ngx_str_t name; 
ngx_uint_t value,; 
} ngx_conf_enum_t; 


其 中 ，name 表 示 配 置 项 后 的 参数 只 能 与 name 指 癌 的 字符 串 相等 ， 
而 value 表 示 如 果 参 数 中 出 现 了 name，ngx_conf_set_enum_slot 方 法 将 会 
把 对 应 的 value 设 置 到 存储 的 变量 中 。 例 如 : 


static ngx_conf_enum t test enums[] = { 
{ ngx_string("apple"), 1 }, 
{ ngx_string("banana"), 2 }, 
{ ngx_string("orange"), 3 }, 
{ ngx_null_ string, 0 } 
}; 
上 面 这 个 例子 表示 ， 配 置 项 中 的 参数 必须 是 apple、banana、orange 
其 中 之 一 。 注 意 ， 必 须 以 ngx_null_string 结 尾 。 需 要 用 ngx_uint t 来 存储 
解析 后 的 参数 ， 在 4.2.1 节 中 是 用 ngx_http_mytest_conf_t 中 的 “ngx_uint_t 


my_enum_sedq;” 来 存储 解析 后 的 枚 举 参数 的 。 在 设置 ngx_command t 


上 时， 需要 把 上 面 例子 中 定义 的 test_enums 数 组 传 给 post 指 针 ， 如 下 所 


修 ° 


static ngx_command_t ngx_http_mytest commands[] = { 


{ ngx_string("test_enum"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1, 
ngx_conf_set_enum_slot, NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_enum_seq), 
test_enums }, 

ngx_null_command 


这 样 ， 如 果 在 nginx.conf 中 出 现 了 配置 项 test_enum banana;， 
my_enum_seq 的 值 是 2。 如 果 配 置 项 test_enum 出 现 了 除 apple、banana、 
orange 之 外 的 值 ，Nginx 将 会 报 “invalid value” 销 误 。 


(12) 


ngx_conf_set_bitmask_slot(ngx_conf_t*cf,ngx_command_t*cmd,void*conf 


); 


ngx_conf_set_bitmask_slot 与 ngx_conf_set_enum_slot 也 是 非常 相似 
的 ， 配 置 项 的 参数 都 必须 是 枚 举 成 员 ， 唯 一 的 差别 在 于 效率 方面 ， 
ngx_conf_set_enum_slot 中 枚 举 成 员 的 对 应 值 是 整 型 ， 表 示 序 列 号 ， 它 
的 取 值 范围 是 整 型 的 范围 ， 而 ngx_conf_set_bitmask_slot 中 枚 举 成 员 的 
对 应 值 虽然 也 是 整 型 ， 但 可 以 按 位 比较 ， 它 的 效率 要 高 得 多 。 也 就 是 
说 ， 整 型 是 4 字 市 (32 位 ) 的 话 ， 在 这 个 枚 举 配置 项 中 最 多 只 能 有 32 
项 。 


由 于 ngx_conf_set_bitmask_slot 与 ngx_conf_set_enum_slot 这 两 个 预 
设 解析 方法 在 名 称 上 的 差别 ， 用 来 表示 配置 项 参数 的 枚 举 取 值 结构 体 
也 由 ngx_conf_enum t 变 成 了 ngx_conf_bitmask_t， 但 它们 并 没有 区 别 。 


typedef struct { 
ngx_str_t name; 
ngx_uint_t mask; 

} ngx_conf_bitmask_t; 


下 面 以 定义 test_bitmasks 数 组 为 例 来 进行 说 明 。 


static ngx_conf_bitmask_t test bitmasks[] = { 
{ ngx_string("good"), Ox0002 }, 
{ ngx_string("better"), Ox0004 }, 
{ ngx_string("best"), Ox0008 }, 
{ ngx_null_ string, 0 } 
}; 


如 果 配 置 项 名 称 定义 为 test_bitmask， 在 nginx.conf 文 件 中 
test_bitmask 配 置 项 后 的 参数 只 能 是 good、better、best 这 3 个 值 之 一 。 我 
们 用 ngx_http_mytest_conf t 中 的 以 下 成 员 : 


ngx_uint_t my_bitmask; 


来 存储 test_bitmask 的 参数 ， 如 下 所 示 。 


static ngx_command t ngx_http_mytest commands[] = { 


{ ngx_string("test_bitmask"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1, 
ngx_conf_set_bitmask_slot, 
NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_mytest_conf_t, my_bitmask), 
test_bitmasks }, 

ngx_null_command 


如 果 在 nginx.conf 中 出 现 配 置 项 test_bitmask best; ， 那 么 my_bitmask 
的 值 是 0x8 。 


(13) ngx_conf set_access_slot 


ngx_conf_set_access_slot 用 于 设置 读 / 写 权限 ， 配 置 项 后 可 以 携带 
1~3 个 参数 ， 因 此 ， 在 ngx_command_t 中 的 type 成 员 要 包含 
NGX_CONF_TAKE123。 参 数 的 取 值 可 参见 表 4-2。 这 里 用 
ngx_http_mytest_conf t 结 构 中 的 “ngx_uint_t my_access;” 来 存储 配置 
项 “test_access” 后 的 参数 值 ， 如 下 所 示 。 


static ngx_command t ngx_http_mytest commands[] = { 


{ ngx_string("test_access"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE123, 
ngx_conf_set_access_slot, 
NGX_HTTP_LOC_CONF_OFFSET， 
offsetof(ngx_http_mytest_conf_t, my_access), 
NULL }, 

ngx_null_command 


}; 


这 样 ，ngx_conf_set_access_slot 束 可 以 解析 读 / 写 权限 的 配置 项 了 。 
例如 ， 当 nginx.conf 中 出 现 配置 项 test_access user:rw group:rw all:r; 时 ， 


my_access 的 值 将 是 436。 


er 注意 “在 ngx_http_mytest_create_loc_conf 创 建 结 构 体 时 ， 如 果 
想 使 用 ngx_conf _set_access_slot， 那 么 必须 把 my_access 初 始 化 为 
NGX_CONF_UNSET_UINT 宏 ， 也 就 是 4.2.1 节 中 的 语句 “mycf- 


>my_access=NGX_CONF_UNSET_UINT;”， 否 则 


ngx_conf_set_access_slot 解 析 时 会 报错 。 
(14) ngx_conf set_path slot 


ngx_conf set_path_slot 可 以 携带 1~4 个 参数 ， 其 中 第 1 个 参数 必须 是 
路 径 ， 第 2~4 个 参数 必须 是 整数 (大 部 分 情形 下 可 以 不 使 用 ) ， 可 以 参 
见 2.4.3 世 中 client body_temp_path 配 置 项 的 用 法 ，client_body_temp_path 
配置 项 就 是 用 ngx_conf_set_path_slot 预 设 方法 来 解析 参数 的 。 


ngx_conf_set_path_slot 会 把 配置 项 中 的 路 径 参 数 转 化 为 ngx_path_t 
结构 ， 看 一 下 ngx_path_t 的 定义 。 


typedef Struct { 
ngx_str_t name; 
size_t len,; 
size_t level[3]; 
ngx_path_manager_pt manager; 
ngx_path_loader_pt loader; 
void *data,; 
u_char *conf_file; 
ngx_uint_t line; 

} ngx_path_t; 


其 中 ，name 成 员 存储 着 字符 串 形式 的 路 径 ， 而 level 数 组 就 会 存储 
着 第 >、 第 3、 第 4 个 参数 (如 果 存 在 的 话 ) 。 这 里 用 
ngx_http_mytest_conf t 结 构 中 的 “ngx_path_t*my_path;” 来 存储 配置 
项 “test_path” 后 的 参数 值 。 


static ngx_command_t ngx_http_mytest commands[] = { 


{ ngx_string("test_path"), 


NGX_HTTP_LOC_CONF | NGX_CONF_TAKE1234, 
ngx_conf_set_path_slot， 
NGX_HTTP_LOC_CONF_OFFSET， 
offsetof(ngx_http_mytest_conf_t, my_path), 
NULL } 

ngx_null_command 


如 果 nginx.conf 中 存在 配置 项 test_path/usr/local/nginx/123;，my_path 
指 癌 的 ngx_path_t 结 构 中 ，name 的 内 容 是 /usr/local/nginx/， 而 level[0] 为 
1，level[1] 为 2，level[2] 为 3。 如 果 配 置 项 
是 “test_path/usrlocalnginx/;”， 那 么 level 数 组 的 3 个 成 员 都 是 0。 


4.2.4 ”上 自 定义 配置 项 处 理 方法 


除了 使 用 Nginx 已 经 实现 的 14 个 通用 配置 项 处 理 方法 外 ， 还 可 以 目 
己 编写 专用 的 配置 项 处 理 方法 。 事 实 上 ，3.5 市 中 的 ngx_http_mytest 整 
征 目 定义 的 处 理 mytest 配 置 项 的 方法 ， 只 是 没有 去 处 理 配置 项 的 参数 而 
已 。 本 世 举 例 说 明 如 何 编写 方法 来 解析 配置 项 。 


假设 我 们 要 处 理 的 配置 项 名 称 是 test_config， 它 接收 1 个 或 者 2 个 参 
数 ， 且 第 1 个 参数 类 型 写字 符 串 ， 第 2 个 参数 必须 是 整 型 。 定 义 结构 体 


来 存储 这 两 个 参数 ， 如 下 所 示 。 


typedef struct { 
ngx_str_t my_config_str,; 


ngx_int_t my_config_num; 
} ngx_http_mytest_conf_t; 


其 中 ，my_config_str 存 储 第 1 个 字符 串 参 数 ，my_config_num 存 储 
第 2 个 数字 参数 。 


首先 ， 我 们 按照 4.2.27mngx_command_s 中 的 set 方 法 指针 格式 来 定 
义 这 个 配置 项 处 理 方法 ， 如 下 所 示 。 


static char* ngx_conf_set myconfig(ngx_conf_t *cf, ngx_command_t *cmd, void 
*conf ); 


接 下 来 定义 ngx_command_t 结 构 体 ， 如 下 所 示 。 


static ngx_command t ngx_http_mytest commands[] = { 


{ ngx_string("test myconfig"), 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE12, 
ngx_conf_set_myconfig, 
NGX_HTTP_LOC_CONF_OFFSET， 

9， 
NULL }, 
ngx_null_command 


}; 


这 样 ，test_myconfig 后 就 公 须 跟着 1 个 或 者 2 个 参数 了 。 现 在 开始 实 
现 ngx_conf_set_myconfig 处 理 方法 ， 如 下 所 示 。 
static char* ngx_conf_set_ myconfig(ngx_conf_t *cf, ngx_command_t *cmd, void *conf) 


{ 


/* 注 意 ， 参 数 


conf 就 是 


HTTP 框 架 传 给 用 户 的 在 


ngx_http_mytest_create_1oc_conf 回 调 方法 中 分 配 的 结构 体 


ngx_http_mytest_conf 七 */ 
ngx_http_mytest_conf t *mycf = conf; 
/* cf->args 是 


个 


ngx_array_t 队 列 ， 它 的 成 员 都 是 


ngx_str_t 结 构 。 我 们 


value 指 向 


ngx_array_t 的 


elts 内 容 ， 其 中 


value[1] 就 是 第 


1 个 参数 ， 同 理 ， 


value[2] 是 第 
2 个 参数 
*/ 


ngx_str_t* Value = cf->args->elts,; 
// ngx_array_t 的 


nelts 表 示 参 数 的 个 数 


if (cf->args->nelts > 1) 
{ 
// 直接 赋值 即 可 ， 


ngx_str_t 结 构 只 是 指针 的 传递 


mycf->my_config_str = value[1]; 
if (cf->args->nelts > 2) 
// 将 字符 串 形式 的 第 


2 个 参数 转 为 整 型 


mycf->my_config_num = ngx_atoi(value[2].data, value[2].1en); 


/* 如 果 字 符 串 转 化 整 型 失败 ， 将 报 “ 


invalid number” 错 误 ， 


Nginx 启 动 失败 


*/ 
If (mycf->my_config_num == NGX_ERROR) { 
return "invalid number"; 
} 


} 
// 返回 成 功 


return NGX_CONF_OK; 


假设 nginx.conf 中 出 现 test_myconfig jordan 23; 配 置 项 ， 那 么 


my_config_str 的 值 是 jordan， 而 my_config num 的 值 是 23。 


4.2.5 ”合并 配置 项 


回顾 一 下 4.1 方 中 的 例子 ， 一 个 test_str 配 置 同时 在 http{.….}、 
server{...}、location/url1{...} 中 出 现时 ， 到 底 以 哪 一 个 为 准 ? 本 节 将 讨 
论 如 何 合并 不 同 配 置 块 间 的 同名 配置 项 ， 前 先 回顾 一 下 4.2.1 市 中 
ngx_http_module_t 的 结构 。 


typedef struct { 


void *(*create_ loc conf)(ngx_conf_t *cf); 
char *(*merge loc conf)(ngx_conf_t *cf, void *prev, void *conf); 


} ngx_http_module_t; 


上 面 这 段 代码 定义 了 create_loc_conf 方 法 ， 意 味 着 HTTP 框 架 会 建 
loc 级 别 的 配置 。 什 么 意思 呢 ? 就 是 说 ， 如 果 没 有 实现 merge_loc_conf 方 
法 ， 也 就 是 在 构造 ngx_http_module_t 时 将 merge_loc_conf 设 为 NULL 
了 ， 那 么 在 4.1 广 的 例子 中 server 块 或 者 http 块 内 出 现 的 配置 项 都 不 会 生 
效 。 如 果 我 们 希望 在 server 块 或 者 http 块 内 的 配置 项 也 生效 ， 那 么 可 以 
通过 merge_loc_conf 方 法 来 实现 。merge_loc_conf 会 把 所 属 父 配置 块 的 


配置 项 与 子 配置 块 的 同名 配置 项 合并 ， 当 然 ， 如 何 合并 取决 于 具体 的 
merge_loc_conf 实 现 。 


merge_loc_conf 有 3 个 参数 ， 第 1 个 参数 仍然 是 ngx_conf_t*cf， 提 供 
一 些 基本 的 数据 结构 ， 如 内 存 池 、 日 志 等 。 我 们 需要 关注 的 是 第 2、 
3 个 参数 ， 其 中 第 2 个 参数 void*prev 是 指 解析 父 配置 块 时 生成 的 结构 
体 ， 而 第 3 个 参数 void*conf 则 指出 的 是 保存 子 配 置 块 的 结构 体 。 


仍 以 4.1 太 的 例子 为 例 ， 来 看 看 如 何 合并 同时 出 现 了 6 次 的 test_str 配 
置 项 ， 如 下 所 示 。 


static char * 
ngx_http_mytest_merge_loc conf(ngx_conf_t *cf, void *parent, void *child) 


ngx_http_mytest_conf_t *prev = (ngx_http_mytest_conf_t *)parent,; 
ngx_http_mytest_conf_t *conf = (ngx_http_mytest conf_t *)child; 
ngx_conf_merge_str_value(conf->my_str, 

prev->my_str, "defaultstr"); 
return NGX_CONF_OK; 


可 以 看 到 ， 只 需要 按照 自己 的 需求 将 父 配置 块 的 值 赋予 子 配 置 块 
即 可 ， 这 时 表示 父 配 置 块 优先 级 更 高 ， 反 过 来 也 是 可 以 的 ， 表 示 子 配 
置 块 的 优先 级 更 高 。 例 如 ， 在 解析 server{...} 块 时 ( 传 入 的 child 参 数 就 
是 当前 server 块 的 ngx_http_mytest_conf t 结 构 ) ， 父 配置 块 (也 就 是 传 
入 的 parent 参 数 ) 就 是 http{...} 块 ， 解 析 location{...} 块 时 父 配置 块 就 是 
server{...} 块 。 


如 何 处 理 父 、 子 配置 块 下 的 同名 配置 项 ， 每 个 HTTP 模 块 部 可 以 目 
由 选择 。 例 如 ， 可 以 简单 地 以 父 配置 奉 换 子 配 置 ， 或 者 将 两 种 不 同 级 
别 的 配置 做 完 运 算 后 再 覆 音 等 。 上 面 的 例子 对 不 同 级 别 下 的 test_str 配 
置 项 的 处 理 是 最 简单 的 ， 下 面 我 们 使 用 Nginx 预 置 的 
ngx_conf_merge_str_value 宏 来 合并 子 配置 块 中 ngx_str_t 类 型 的 my_str 成 
员 ， 看 看 ngx_conf_merge_str_value 到 底 做 了 哪些 事情 。 


#define ngx_conf_merge_ str_value(conf, prev, default) 和 
// 当前 配置 块 中 是 否 已 经 解析 到 


test_str 配 置 项 


if (conf.data == NULL){ \ 
// 父 配置 块 中 是 否 已 经 解析 到 


test_str 配 置 项 


if (prev.data) { 
// 将 父 配置 块 


test_str 参 数值 直接 覆盖 当前 配置 块 的 


\ 
P 的 


test_str 
conf,len = prev.1len,; \ 
conf ,data = prev.data; \ 
} else { \ 
/* 如 果 父 配置 块 和 子 配置 块 都 没有 解析 到 


test_str,， 以 


default 参 数 作为 默认 值 传 给 当前 配置 块 的 


test_str*/ 
conf ,len = sizeof(default) - 1; \ 
conf ,data = (u_char *) default; \ 
} \ 
} 


事实 上 ，Nginx 预 设 的 配置 项 合并 方法 有 10 个 ， 它 们 的 行为 与 上 壕 
的 ngx_conf_merge_str_value 是 相似 的 。 参 见 表 4-5 中 Nginx 已 经 实现 好 的 


S 


个 简单 的 配置 项 合并 宏 ， 它 们 的 参数 类 型 与 
ngx_conf_ merge_str_value 一 致 ， 而 且 除 了 ngx_conf_ merge_bufs_value 
外 ， 它 们 都 将 接收 3 个 参数 ， 分 别 表示 父 配置 块 参数 、 子 配置 块 参数 、 


默认 值 。 


表 4-5 Nginx 预 设 的 10 种 配置 项 合并 安 


配置 项 合并 宏 


ngx conf merge value 


ngx conf merge ptr value 


ngx_ conf merge uint value 


ngx_conf merge msec value 


配置 项 合并 宏 


ngx conf merge sec value 


ngx conf merge size value 


ngx conf merge off value 


ngx conf merge str_value 


ngx conf merge bufs value 


ngx conf merge bitmask value 


意 义 

合并 可 以 使 用 等 号 (=) 直接 赋值 的 变量 ， 并 且 该 变量 在 create_loc_conf 等 
分 配方 法 中 初始 化 为 NGX_CONF_UNSET， 这 样 类 型 的 成 员 可 以 使 用 ngx 
conf_merge_value 合并 安 

合并 指针 类 型 的 变量 ， 并 且 该 变量 在 create loc_conf 等 分 配方 法 中 初始 化 
为 swing 这 样 类 型 的 成 员 可 以 使 用 ngx_conf merge_ptr_ 
value 合并 安 

合并 整数 类 型 的 变量 ， 并 且 该 变量 在 create_ loc_conf 等 分 配方 法 中 初始 化 为 

Ne 6 ee ee 这 样 类 型 的 成 员 可 以 使 用 ngx_conf merge_uint 
value 合并 安 


合并 表示 毫秒 的 ngx_msec t 类 型 的 变量 ， 并 且 该 变量 在 create_ loc_conf 等 
分 配方 法 中 初始 化 为 NGX_CONF Te 这 样 类 型 的 成 员 可 以 使 用 
ngx_conf merge_msec_value 合并 安 


合并 表示 秒 的 time_t 类 型 的 变量 ， 并且 该 变量 在 create_loc_conf 等 分 配方 法 
中 初始 化 为 NGX_CONF_UNSET， 这 样 类 型 的 成 员 可 以 使 用 ngx_conf merge_ 


sec_value 合并 宏 


se 


合并 size t 等 表示 空间 长 度 的 变量 ， 并 且 该 变量 在 create loc_conf 等 分 配 
方法 中 初始 化 为 NGX_CONF_UNSET SIZE， 这 样 类 型 的 成 员 可 以 使 用 ngx_ 
conf merge_size_value 合并 宏 

合并 off t 等 表示 偏 移 量 的 变量 ， 并 且 该 变量 在 create loc_conf 等 分 配方 法 
中 初始 化 为 NGX_ CONF UNSET， 这 样 类 型 的 成 员 可 以 使 用 ngx_conf merge_ 
of value 合并 安 

ngx_str t 类 型 Ee 可 以 使 用 ngx_conf merge_str_value 合并 ， 这 时 传人 的 
default 参数 必须 是 一 个 char* 字符 串 
ngx_bufs t 类 型 成 员 可 以 使 用 ngx_conf_merge_bufs_value 合并 宏 ， 这 时 传 
人 的 default 参数 是 两 个 ， 因 为 ngx_bufs t 类 型 有 两 个 成 员 ， 所 以 需要 传人 两 
一 二 
外 二 进 制 位 来 表示 标志 位 的 整 型 成 员 ， 可 以 使 用 ngx_conf merge_bitmask 


value 并 安 


在 4.3.3 广 中 我 们 会 看 到 HTTP 框 架 在 什么 时 候 会 调用 各 模块 的 


merge_loc_conf 方 法 或 者 merge_srv_conf 方 法 。 


4.3 _ HTTP 配置 模型 


上 文中 我 们 了 解 了 如 何 使 用 Nginx 提 供 的 预 设 解析 方法 来 处 理 自 己 
感 兴趣 的 配置 项 ， 由 于 http 配 置 项 设计 得 有 些 复杂 ， 为 了 更 清晰 地 使 用 
好 ngx_command t 结 构 体 处 理 http 配 置 项 ， 本 世 将 简单 讨论 HTTP 配 置 模 
型 是 怎样 实现 的 ， 在 第 10 章 我 们 会 从 HTTP 框 架 的 角度 谈 谈 它 是 怎么 管 
理 每 一 个 HTTP 模 块 的 配置 结构 体 的 。 


当 Nginx 检 测 到 http{...} 这 个 天 键 配 置 项 时 ，HTTP 配 置 模型 束 局 动 
了 ， 这 时 会 首先 建立 1 个 ngx_http_conf_ctx_t 结 构 。 下 面 看 一 下 
ngX_http_conf_ctx_t 的 定义 。 


typedef struct { 
/* 指 针 数 组 ， 数 组 中 的 每 个 元 素 指向 所 


HTTP 模 块 


create_main_conf 方 法 产生 的 结构 体 


vA 
void **main_conf,; 
/* 指 针 数 组 ， 数 组 中 的 每 个 元 素 指向 所 有 


HTTP 模 块 


create_srv_conf 方 法 产生 的 结构 体 


wh 


void **srv_conf; 
/* 指 针 数 组 ， 数 组 中 的 每 个 元 素 指 向 所 


HTTP 模 块 


create_loc_conf 方 法 产生 的 结构 体 


*/ 
void **]loc_conf; 
} ngx_http_conf_ctx_t; 


这 时 ，HTTP 框 架 会 为 所 有 的 HTTP 模 块 建立 3 个 数组 ， 分 别 存放 所 
有 HTTP 模 块 的 create_main_conf、create_srv_conf、create_loc_conf 方 法 
返回 的 地 址 指针 ( 束 像 本 章 的 例子 中 mytest 模 块 在 create_loc_conf 中 生 
成 了 ngx_http_mytest_conf t 结 构 ， 并 在 create_loc_conf 方 法 返回 时 将 指 
针 传 递 给 HTTP 框 架 ) 。 当 然 ， 如 采 HTTP 模 块 对 于 配置 项 不 感 兴 
它 没有 实现 create_main_conf、create_srv_conf、create_loc_conf 等 方 

那么 数组 中 相应 位 置 存储 的 指针 是 NULL 。ngx_http_conf_ctx_tHJ3 
个 成 员 main_conf、srv_conf、loc_conf 分 别 指向 这 3 个 数组 。 下 面 看 一 段 
简化 的 代码 ， 了 解 如 何 设置 create loc_conf 返 回 的 地 址 。 


ngx_http_conf_ctx_t *ctx; 
// HTTP 框 架 生成 了 


1 


ngx_http_conf_ctx_t 结 构 


ctx = ngx_pcalloc(cf->pool, sizeof(ngx_http_conf_ctx_t)); 
if (ctx == NULL) { 
return NGX_CONF_ERROR; 


} 
// 生成 


1 个 数组 存储 所 有 


I 


的 


HTTP 模 块 


create_1oc_conf 方 法 返回 的 地 址 


ctx->loc_conf = ngx_pcalloc(cf->pool, sizeof(void *) * ngx_http_max_module); 
If (ctx->loc conf == NULL) { 
return NGX_CONF_ERROR; 


} 
// 遍历 所 有 的 


HTTP 模 块 


for (m = 0; ngx_modules[m]; m++) 
If (ngx_modules[m]->type != NGX_HTTP_MODULE) { 
continue; 
下 


module = ngx_modules[m]->ctx; 
mi = ngx_modules[m]->ctx_index; 
/* 如 果 这 个 


HTTP 模 块 实现 了 


它 ， 并 把 返回 的 地 址 存储 到 


create_loc_conf， 就 调 


loc_conf 中 


if (module->create loc conf) { 
ctx->loc_conf[mi] = module->create loc _conf(cf); 
if (ctx->loc_conf[mi] == NULL) { 
return NGX_CONF_ERROR; 
} 


这 样 ， 在 http{...} 块 中 就 通过 1 个 ngx_http_conf_ctx_t 结 构 保 存 了 所 
有 HTTP 模 块 的 配置 数据 结构 的 入 口 。 以 后 遇 到 任何 server{.…} 块 或 者 
location{...} 块 时 ， 也 会 建立 ngx_http_conf_ctx_t 结 构 ， 生 成 同样 的 数组 
来 保存 所 有 HTTP 模 块 通过 create_srv_conf、create_loc_conf 等 方法 返回 
的 指针 地 址 。ngx_http_conf_ctx_t 是 了 解 http 配 置 块 的 基础 ， 下 面 我 们 
来 看 看 具体 的 解析 流程 。 


4.3.1 解析 HTTP 配 置 的 流程 


图 4-1 是 HTTP 框 染 解析 配置 项 的 示意 流程 图 (图 中 出 现 了 
ngx_http_module 和 ngx_http_core_module 模 块 ， 所 谓 的 HTTP 框 染 主 要 由 
这 两 个 模块 组 成 ， 下 面 解释 图 中 每 个 流程 的 意义 。 


1 1. 解析 配 置 文 作 一 | | | 
六 
1 2. 发 现 ntp 配置 项 | 
| 
| | 
可 3. 初始 化 每 一 个 HTTP 模 块 | 
| ; 4. 依次 调用 各 模块 的 create 和 、SIV 、loc ) _conf 
| | | | | 
| | 
| | | pad 科 | 
| | A ee + 
. | | 6. NE | 
| | | | 让 
| | | | 
| | 这 人 es Ey 
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' | ' 一 一 
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| 19. http 配置 项 处 理 完毕 1 | | 
. | | | 
| f | | 
| | | 20. 合并 不 同 块 内 的 同名 配置 项 | 
| | 
| 21. http 本 cE 置 项 处 理 完毕 | , | 
i 
| 22. 桓 项 处 理 完 毕 | | ! 


图 4-1 解析 http 配 置 项 的 示意 流程 图 


1) 图 4-1 中 的 主 循 环 是 指 Nginx 进 程 的 主 循环 ， 主 循环 只 有 调用 配 
置 文 件 解 析 器 才能 解析 nginx.conf 文 件 “这 里 的 “ 主 循环 ”是 指 解析 全 间 
配置 文件 的 循环 代码 ， 图 8-6 的 第 4 步 ， 为 了 便于 理解 ， 可 以 认为 是 
Nginx 框 架 代码 在 循环 解析 配置 项 ) 。 


2) 当 发 现 配 置 文件 中 含有 http{} 关 键 字 时 ，HTTP 框 架 开 始 启动 ， 
这 一 过 程 详 见 10.7 广 描述 的 ngx_http_block 方 法 。 


3) HTTP 框 架 会 初始 化 所 有 HTTP 模 块 的 序列 号 ， 并 创建 3 个 数组 
用 于 存储 所 有 HTTP 模 块 的 create_main conf 、create_srv_conf 、 
create_loc_conf 方 法 返回 的 指针 地 址 ， 并 把 这 3 个 数组 的 地 址 保存 到 


ngx_http_conf_ctx_t 结 构 中 。 


4) 调用 每 个 HTTP 模 块 (当然 也 包括 例子 中 的 mytest 模 块 ) 的 
create_ main conf、create_sry_conf、create_loc_conf (如 果实 现 的 话 ) 


方 优 有 


5) 把 各 HTTP 模 块 上 述 3 个 方法 返回 的 地 址 依次 保存 到 
ngx_http_conf_ctx_t 结 构 体 的 3 个 数组 中 。 


6) 调用 每 个 HTTP 模 块 的 preconfiguration 方 法 (如 果实 现 的 话 ) 。 


7) 注意 ， 如 果 preconfiguration 返 回 失败 ， 那 么 Nginx 进 程 将 会 停 
EE o 


8) HTTP 框 架 开 始 循环 解析 nginx.conf 文 件 中 http{...} 里 面 的 所 有 配 
置 项 ， 注 意 ， 这 个 过 程 到 第 19 步 才 会 返回 。 


9) 配置 文件 解析 器 在 检测 到 1 个 配置 项 后 ， 会 遍历 所 有 的 HITP 模 
块 ， 检 查 它 们 的 ngx_command_t 数 组 中 的 name 项 是 否 与 配置 项 名 相 
辣 攻 


10) 如 果 找 到 有 1 个 HITP 模 块 〈 如 mytest 模 块 ) 对 这 个 配置 项 感 兴 
趣 (如 test_myconfig 配 置 项 ) ， 就 调用 ngx_command_t 结 构 中 的 set 方 法 
人 


11) set 方 法 返回 是 否 处 理 成 功 。 如 果 人 处 理 失败 ， 那 么 Nginx 进 程 会 


12) 配置 文件 解析 器 继续 检测 配置 项 。 如 果 发 现 server{.…} 配 置 
项 ， 就 会 调用 ngx_http_core_module 模 块 来 处 理 。 因 为 
ngx_http_core_module 模 块 明确 表示 项 望 处 理 server{} 块 下 的 配置 项 。 注 
意 ， 这 次 调用 到 第 18 步 才 会 返回 。 


13) ngx_http_core_module 模 块 在 解析 server{...} 之 前 ， 也 会 如 第 3 
一 样 建立 ngx_http_conf _ctx_t 结 构 ， 并 建立 数组 保存 所 有 HTTP 模 块 返 
回 的 指针 地 址 。 然 后 ， 它 会 调用 每 个 HTTP 模 块 的 create_srv_conf、 
create_loc_conf 方 法 (如 果实 现 的 话 ) 


14) 将 上 一 步 各 HTTP 模 块 返 回 的 指针 地 址 保存 到 
ngx_http_conf_ctx_t 对 应 的 数组 中 。 


15) 开始 调用 配置 文件 解析 器 来 处 理 server{...} 里 面 的 配置 项 ， 注 


意 ， 这 个 过 程 在 第 17 步 返回 。 


16) 继续 重复 第 9 步 的 过 程 ， 遍 历 nginx.conf 中 当前 server{..} 内 的 
所 有 配置 项 。 


17) 配置 文件 解析 器 继续 解析 配置 项 ， 发 现 当 前 server 块 已 经 遍历 
到 尾部 ， 说 明 server 块 内 的 配置 项 处 理 完 毕 ， 返 回 ngx_http_core_module 
模块 。 


18) http core 模 块 也 处 理 完 server 配 置 项 了 ， 返 回 至 配置 文件 解析 
锅 继 续 解析 后 面 的 配置 项 。 


19) 配置 文件 解析 器 继续 解析 配置 项 ， 这 时 发 现 处 理 到 了 http{...} 
的 尾部 ， 返 回 给 HTTP 框 架 继 续 处 理 。 


20) 在 第 3 步 和 第 13 步 ， 以 及 我 们 没有 列 出 来 的 某 些 步骤 中 (如 发 
现 其 他 server 块 或 者 location 块 ， 都 创建 了 ngx_http_conf_ctx_t 结 构 ， 
这 时 将 开始 调用 merge_srv_conf、merge_loc_conf 等 方法 合并 这 些 不 同 


块 (http、server、location) 中 每 个 HTTP 模 块 分 配 的 数据 结构 。 


21) HTTP 框 架 处 理 完 毕 http 配 置 项 (也 就 是 ngx_command_t 结 构 中 
的 set 回 调 方法 处 理 完毕 ) ， 权 回 给 配置 文件 解析 妖 继 续 处 理 其 他 
http{.….} 外 的 配置 项 。 


22) 配置 文件 解析 器 处 理 完 所 有 配置 项 后 会 告诉 Nginx 主 循环 配置 


项 解析 完毕 ， 这 时 Nginx 才 会 启动 Web 服 务 器 。 


@@ 注音 “图 4.1 并 没有 列 出 解析 location{.} 块 的 流程 ， 实 际 上 ， 
解析 ]ocation 与 解析 server 并 没有 本 质 上 的 区 别 ， 为 了 人 简化 起 见 ， 没 有 把 
它 画 到 图 中 。 


4.3.2 HTTP 配 置 模 型 的 内 存 布局 


了 解 内 存 布局 ， 会 帮助 理解 使 用 create_main_conf 、 
create_srv_conf、create_loc_conf 等 方法 在 内 存 中 创建 了 多 少 个 存放 配置 
项 的 结构 体 ， 以 及 最 终 处 理 请 求 时 ， 使 用 到 的 是 哪个 结构 体 。 我 们 已 
经 看 到 ，http{} 块 下 有 1 个 ngx_http_conf_ctx_t 结 构 ， 而 每 一 个 server{} 块 
下 也 有 1 个 ngx_http_conf_ctx_t 结 构 ， 它 们 的 关系 如 图 4-2 所 示 。 


图 4-2 描 述 了 http 块 与 某 个 server 块 下 存储 配置 项 参数 的 结构 体 间 的 
关系 。 某 个 server 块 下 ngx_http_conf_ctx_t 结 构 中 的 main_conf 数 组 将 通 
过 直接 指向 来 复 用 所 属 的 http 块 下 的 main_conf 数 组 (其 实 是 说 server 块 
下 没有 main 级 别 配 置 ， 这 是 显然 的 ) 。 


可 以 看 到 ，ngx_http_conf_ctx_t 结 构 中 的 main_conf、srv_conf、 
loc_conf 数 组 傈 存 了 所 有 HTTP 模 块 使 用 create_main_conf、 
create_srv_conf、create_loc_conf 方 法 分 配 的 结构 体 地 址 。 每 个 HTTP 模 
块 都 有 自己 的 序号 ， 如 第 1 个 HTTP 模 块 就 是 ngx_http_core_module 模 
块 。 当 在 http{...} 内 遍历 到 第 2 个 HTTP 模 块 时 ， 这 个 HTTP 模 块 已 经 使 用 
create_main_conf 、create_srv_conf、create_loc_conf 方 法 在 内 存 中 创建 
了 3 个 结构 体 ， 并 把 地 址 放 到 了 ngx_http_conf_ctx_t 内 3 个 数组 的 第 2 个 成 
员 中 。 在 解析 server{...} 块 时 人 遍历 到 第 2 个 HTTP 模 块 时 ， 除 了 不 调用 
create_main_conf 方 法 外 ， 其 他 完全 与 http{.….} 内 的 处 理 一 致 。 


当 人 解析 到 ]ocation{...} 块 时 ， 也 会 生成 1 个 ngx_http_conf_ctx_t 结 构 ， 
其 中 的 3 个 指针 数组 与 server{...}、http{...} 块 内 ngx_http_conf_ctx_t 结 构 
的 天 系 如 图 4-3 所 示 。 


从 图 4-3 可 以 看 出 ， 在 解析 location{..} 块 时 只 会 调用 每 个 HTTP 模 块 
的 create_loc_conf 方 法 创建 存储 配置 项 参数 的 内 存 ，ngx_http_conf_ctx_t 
结构 的 main_conf 和 srv_conf 都 直接 引用 其 所 属 的 server 块 下 的 
ngx_http_conf_ctx_t 结 构 。 这 也 是 显然 的 ， 因 为 location{..….} 块 中 当然 没 
有 main 级 别 和 srv 级 别 的 配置 项 ， 所 以 不 需要 调用 各 个 HTTP 模 块 的 
create_main_conf、create_srv_conf 方 法 生成 结构 体 存放 main、srv 配 置 
请 


http 块 下 的 ngx_http _conf _ctx _t 


所 有 HTTP 模 块 create 
_main_conf 产生 ed 


第 2 个 HTTP 模 块 存储 所 有 HTTP 模 块 create _srv_ _conf 产生 的 指针 
ie 、 由 


| 


所 有 HTTP 模 块 create_loc _conf 产生 的 指针 


create _srv_conf of 分 配 


的 结构 体 


证 2 不 HTTP 模 天 在 俩 某 个 server 块 下 的 ngx_http _conf _ctx _t 
main 级别 配置 、 由 


ae Jow, oonf i ”a 
Ee 


所 有 HTTP 模块 create _srv_conf 产生 的 指针 


| 


所 有 HTTP 模 块 create loc_ conf 产生 的 指针 


第 2 个 HTTP 模 块 存储 


an | 指 H2| | 
create_srv_conf 分 配 


的 结构 体 


srv 级 区 吕 配 置 、 由 


create _loc _conf 分 配 


的 结构 体 


图 4-2 ”http 块 与 server 块 下 的 ngx_http_conf_ctx_t 所 指向 的 内 存 间 的 关系 


图 4-2 和 图 4-3 说 明了 一 个 事实 : 在 解析 nginx.conf 配 置 文件 时 ， 
旦 解析 到 http{} 块 ， 将 会 调用 所 有 HTTP 模 块 的 create_main_conf、 


create_srv_conf、create_loc_conf 方 法 创建 3 组 结构 体 ， 以 便 存 放 各 个 
HTTP 模 块 感 兴趣 的 main 级 别 配置 项 ， 在 解析 a 到 任何 一 个 server{} 块 

时 ， 又 会 调用 所 有 HTTP 模 块 的 create_srv_conf、create_loc_conf 方 法 创 
建 两 组 结构 体 ， 以 存放 各 个 HITP 模 块 感 兴趣 的 srv 级 别 配置 项 ;在 解析 
到 任何 一 个 location{} 块 时 ， 则 会 调用 所 有 HTTP 模 块 的 create_loc_conf 
方法 创建 1 组 结构 体 ， 用 于 存放 各 个 HTTP 模 块 感 兴趣 的 loc 级 别 配 置 

项 。 


http 块 下 的 ngx_http _conf _ctx _t 


某 server 块 下 的 ngx_http _conf _ctx tt 
| 


该 server 所 属 的 某 个 location 
块 下 的 ngx_http _conf _ctx_t 


所 有 HTTP 模 块 create_loc _conf 产生 的 指针 
指针 1| 指针 2| .| 


第 2 个 HTTP 模块 存储 
loc 级 别 配 置 、 由 
create _loc_conf 分 配 
的 结构 体 


图 4-3 ”location 块 与 http 块 、server 块 下 分 配 的 内 存 天 系 
这 个 事实 告诉 我 们 ， 在 nginx.conf 配 置 文件 中 http{}、server{}、 


location{} 块 的 总 个 数 有 和 多少， 我 们 开发 的 HTTP 模 块 中 create_loc_conf 
方法 (如 果实 现 的 话 ) 就 会 被 调用 多 少 次 ，http{}、server{} 块 的 总 个 


数 有 多 少 ，create_srv_conf 方 法 (如 果实 现 的 话 ) 就 会 被 调用 多 少 次 ;由 
于 只 有 一 个 http{}， 所 以 create_main_conf 方 法 只 会 被 调用 一 次 。 这 3 个 
方法 每 被 调用 一 次 ， 惑 会 生成 一 个 结构 体 ，Nginx 的 HTTP 框 染 居然 创 
建 了 如 此 多 的 结构 体 来 存放 配置 项 ， 怎 样 理解 呢 ? 很 简单 ， 就 是 为 了 
解决 同名 配置 项 的 合并 问题 。 


如 果实 现 了 create_ main_conf 方 法 ， 它 所 创建 的 结构 体 只 会 存放 直 
接 出 现在 http{} 抉 下 的 配置 项 ， 那 么 create_main_conf 只 会 被 调用 一 次 。 


如 果实 现 了 create_srv_conf 方 法 ， 那 么 它 所 创建 的 结构 体 既 会 存放 
直接 出 现在 http{} 块 下 的 配置 项 ， 也 会 存放 直接 出 现在 server{} 块 下 的 
配置 项 。 为 什么 呢 ? 这 其 实 是 HTTP 框 架 的 一 种 优秀 设计 。 例 如 ， 虽 然 
某 个 配置 项 是 针对 于 server 虚 拟 主 机 才 生 效 的 ， 但 http{} 下 面 可 能 有 多 
个 server{} 块 ， 对 于 用 户 来 说 ， 如 果 布 望 在 http{} 下 面 写 入 了 这 个 配置 
项 后 对 所 有 的 server{} 块 都 生效 ， 这 应 当 是 允许 的 ， 因 为 它 减 少 了 用 户 
的 工作 量 。 而 对 于 HTTP 框 架 而 言 ， 就 需要 在 解析 直属 于 http{} 块 内 的 
配置 项 时 ， 调 用 create_srv_conf 方 法 产生 一 个 结构 体 存 放 配 置 ， 解 析 到 
一 个 server{} 块 时 再 调用 create_srv_conf 方 法 产生 一 个 结构 体 存放 配置 ， 
最 后 通过 把 这 两 个 结构 体 合并 解决 两 个 问题 ， 有 一 个 配置 项 在 http{} 块 
内 出 现 了 ， 在 server{} 块 内 却 没 有 出 现 ， 这 时 以 http 块 内 的 配置 项 为 
准 ， 可 如 果 这 个 配置 项 同时 在 http{} 块 、server{} 块 内 出 现 了 ， 它 们 的 


值 又 不 一 样 ， 此 时 应 当 由 对 它 感 兴趣 的 HITP 模 块 来 决定 配置 项 以 哪个 
为 准 。 


如 果实 现 了 create_loc_conf 方 法 ， 那 么 它 所 创建 的 结构 体 将 会 出 现 
在 http{}、server{}、location{} 块 中 ， 理 由 同上 。 这 是 一 种 非常 人 性 化 
的 设计 ， 充 分 考虑 到 nginx.conf 文 件 中 高 级 别 的 配置 可 以 对 所 包含 的 低 
级 别 配置 起 作用 ， 同 时 也 给 出 了 不 同 级 别 下 同名 配置 项 冲突 时 的 解决 
方案 (可 以 由 HTTP 模 块 自行 决定 其 行为 ) 。4.3.3 广 中 将 讨论 HTTP 框 
架 如 何 合 并 可 能 出 现 的 冲突 配置 项 。 在 10.2 市 会 详细 讨论 HTTP 框 架 怎 
样 管理 HTTP 模 块 产生 的 如 此 多 的 结构 体 ， 以 及 每 个 HTTP 模 块 在 处 理 
请 求 时 ，HTTP 框 架 又 是 怎样 把 正确 的 配置 结构 体 告 诉 它 的 。 


4.3.3 如何 合并 配置 项 


在 4.3.1 下 描述 的 http 配 置 项 处 理 序列 图 (图 4-1) 中 可 以 看 到 ， 在 
第 20 步 ，HTTP 框 架 开 始 合并 http{}、server{}、location{} 不 同 块 下 各 
HTTP 模 块 生 成 的 存放 配置 项 的 结构 体 ， 那 么 合并 配置 的 流程 是 怎样 进 
行 的 呢 ? 本 市 将 简单 介绍 这 一 工作 流程 ， 而 在 10.2.4 节 中 会 利用 源 代码 


完整 地 说 明 它 。 


图 4-4 是 合并 配置 项 过 程 的 活动 图 ， 它 主要 包含 四 大 部 分 内 容 。 


:如果 HTTP 模 块 实现 了 merge_srv_conf 方 法 ， 就 将 http{..} 块 下 
create_SrV_conf 生 成 的 结构 体 与 过 历 每 一 个 server{..} 配 置 块 下 的 结构 体 
做 merge_srv_conf 操 作 。 


-如果 HTTP 模 块 实 现 了 merge_loc_conf 方 法 ， 就 将 http{...} 块 下 
create_loc_conf 生 成 的 结构 体 与 舱 套 的 每 一 个 server{...} 配 置 块 下 生成 的 
结构 体 做 merge_loc_conf 操 作 。 


-如果 HTTP 模 块 实现 了 merge_loc_conf 方 法 ， 就 将 server{...} 块 下 
create_loc_conf 生 成 的 结构 体 与 舱 套 的 每 一 个 location{...} 配 置 块 下 
create_loc_conf 生 成 的 数据 结构 做 merge_loc_conf 操 作 。 


:如果 HTTP 模 块 实 现 了 merge_loc_conf 方 法 ， 就 将 location{...} 块 下 
create_ loc_conf 生 成 的 结构 体 与 继续 租 套 的 每 一 个 location{.…} 配 置 块 下 
create_loc_conf 生 成 的 数据 结构 做 merge_loc_conf 操 作 。 注 意 ， 这 个 动作 
会 无 限 地 递归 下 去 ， 也 就 是 说 ，location 配 置 块 内 继续 租 套 location， 而 
航 套 多 少 层 在 本 节 中 是 不 受 HITP 框 架 限 制 的 。 不 过 在 图 4-4 没 有 表达 出 
无 限 地 递归 处 理 骨 套 location 块 的 意思 ， 仅 以 location 中 再 和 能 套 一 个 
location 作 为 例子 出 单 说 明 一 个。 


依 序 遍历 所 有 的 HTTP 模 块 


[获取 将 要 执行 合并 配置 项 的 HTTP 模块 ] 


[已 经 处 理 完 所 有 HTTP 模 块 ] 


[遍历 到 一 个 HTTP 模块 ] 


[遍历 完 所 有 的 server 块 ] 
所 有 历 当前 HTTP 模 块 在 所 有 server 块 下 生成 的 结构 体 


[获取 该 HTTP 模 块 在 所 有 server 块 下 生成 的 结构 体 ] 


[获取 到 某 个 server 块 下 生成 的 结构 体 ] 


[如果 实现 了 merge_srv _conf 方法 ] 
[没有 实现 merge_loc _conf ] [merge_srv _conf 方法 没有 实现 ] 


用 merge_srv _conf 合并 http 块 、server 抉 下 create _srv _conf 产生 的 结构 体 


[是 否 实现 merge_loc _conf 方法 ] 


[遍历 完 所 有 的 location 块 ] 
[如 果实 现 了 merge_loc _conf 方法 ] 


用 merge_loc _conf 合并 http 块 、server 块 下 create _loc _conf 方法 产生 的 结构 体 


裔 历 该 server 块 下 嵌 套 的 所 有 location 块 生 成 的 结构 体 


[获取 该 HTTP 模块 在 所 有 location 块 下 生成 的 结构 体 ] 


[获取 到 location 块 ] 


用 merge_loc _conf 合并 server 块 、location 块 下 create_loc _conf 产生 的 结构 体 


遍历 完 所 有 的 子 location 块 ] 
遍历 在 该 location 块 再 次 嵌 套 的 所 有 location 块 下 生成 的 结构 体 
[获取 location 下 要 套 的 location 块 ] 


[获取 到 子 location 块 ] 


用 merge_loc _eonf 合并 location 块 和 甚 峙 套 location 块 下 create_loc _conf 产生 的 结构 体 


图 4-4 解析 完 所 有 http 配 置 项 后 合并 配置 的 流程 图 


图 4-4 包 括 4 重 循环 ， 第 1 层 (最 外 层 ) 损 历 所 有 的 HTTP 模 块 ， 第 2 
层 抽 历 所 有 的 server{.…} 配 置 块 ， 第 3 层 是 裔 历 某 个 server{} 块 中 骸 套 的 
所 有 location{.….} 块 ， 第 4 层 志 历 某 个 location{} 块 中 继续 骨 套 的 所 有 
location 块 《实际 上 ， 它 会 一 直 递 归 下 去 以 解析 可 能 被 层 层 代 套 的 
location 块 ， 详 见 10.2 节 ) 。 读 者 可 以 对 照 上 述 4 重 循环 来 理解 合并 配置 
项 的 流程 图 。 


4.3.4” 预 设 配 置 项 处 理 方法 的 工作 原理 


在 4.2.4 广 中 可 以 看 到， 目 定 义 的 配置 项 处 理 方法 读 取 参 数值 也 是 
很 简单 的 ， 直 接 使 用 ngx_str_t*value=cf->args->elts; 就 可 以 获取 参数 。 
接 下 来 将 把 参数 赋值 到 ngx_http_mytest_conf t 结 构 体 的 相应 成 员 中 。 不 
过 ， 预 设 的 配置 项 处 理 方法 并 不 知道 每 个 HTTP 模 块 所 定义 的 结构 体 包 
括 哪些 成 员 ， 那 么 ， 它 们 怎么 可 以 做 到 具有 通用 性 的 呢 ? 


很 他 单 ， 返 回 到 4.2.2 广 束 可 以 看 天 ，ngx_command_t 结 构 体 的 
offset 成 员 已 经 进行 了 正确 的 设置 (实际 存储 参数 的 成 员 相 对 于 整个 结 
构 体 的 偏 移 位 置 ，Nginx 配 置 项 解析 模块 在 调用 ngx_command_t 结 构 
体 的 set 回 调 方 法 时 ， 会 同时 把 offset 偏 移 位 置 传 进来 。 每 种 预 设 的 配置 
项 解析 方法 都 只 解析 特定 的 数据 结构 ， 也 束 是 说 ， 它 们 既 知 道 存 储 参 


数 的 成 员 相 对 于 整个 结构 体 的 仿 移 量 ， 叉 知道 这 个 成 员 的 数据 类 型 ， 
目 然 可 以 做 到 具有 通用 性 了 。 


下 面 以 读 取 数字 配置 项 的 方法 ngx_conf_set_num_slot 为 例 ， 说 明 预 
设 的 14 个 通用 方法 是 如 何 解析 配置 项 的 。 


char * ngx_conf_set num slot(ngx_conf_t *cf, ngx_command_t *cmd, void *conf ) 


// 指针 


conf 就 是 存储 参数 的 结构 体 的 地 址 


char *p = conf,; 
ngx_int_t *np; 
ngx_str_t *value,; 
ngx_conf_post_t *post; 
/* 根 据 


ngx_command_t 中 的 


offset 偏 移 量 ， 可 以 找到 结构 体 中 的 成 员 ， 而 对 于 


ngx_conf_set_num_slot 方 法 而 言 ， 存 储 数 字 的 必须 是 


ngx_int_t 类 型 


“~ 
np = (ngx_int _t *) (p + cmd->offset); 
/* 在 这 里 可 以 知道 为 什么 要 把 使 


ngx_conf_set_num_slot 方 法 解析 的 成 员 在 


create_loc_conf 等 方法 中 初始 化 为 


NGX_CONF_UNSET， 否 则 是 会 报错 的 
*/ 
if (*np != NGX_CONF_UNSET) { 
return "is duplicate"; 


} 
// value 将 指向 配置 项 的 参数 


value = cf->args->elts,; 


/将 字符 串 的 参数 转化 为 整 型 ， 并 设置 到 


create_loc_conf 等 方法 生成 的 结构 体 的 机 


I 


关 成 员 上 


* 

/ 
*np = ngx_atoi(value[1].data, value[1].1en); 
if (*np == NGX_ERROR) { 


return "Invalid number'"， 


} 
// 如 果 


ngx_command_t 中 的 


post 已 经 实现 ， 那 么 还 需要 调 


post->post_handler 方 法 


if (cmd->post) { 
post = cmd->post; 
return post->post_handler(cf, post, np); 


} 
return NGX_CONF_OK; 


可 以 看 到 ， 这 是 一 种 非常 灵活 和 巧妙 的 设计 。 


4.4 error 日 志 的 用 法 


Nginx 的 日 志 模块 〈《 这 里 所 说 的 日 志 模块 是 ngx_errlog_module 模 

块 ， 而 ngx_http_log_module 模 块 是 用 于 记录 HTTP 请 求 的 访问 日 志 的 ， 
两 者 功能 不 同 ， 在 实现 上 也 没有 任何 关系 ) 为 其 他 模块 提供 了 基本 的 
记录 日 志 功 能 ， 本 章 提 到 的 mytest 模 块 当然 也 可 以 使 用 日 志 模 块 提供 的 
接口 。 出 于 跨 平台 的 考虑 ， 日 志 模块 提供 了 相当 多 的 接口 ， 主 要 是 因 
为 有 些 平 台 下 不 文 持 可 变 参数 。 本 节 主 要 讨论 文 持 可 变 参数 的 日 志 接 
口 ， 事 实 上 不 支持 可 变 参数 的 日 志 接口 在 实现 方面 与 其 并 没有 太 大 的 
不 同 (参见 表 4-9) 。 首 先 看 一 下 日 志 模 块 对 于 支持 可 变 参数 平台 而 提 
供 的 3 个 接口 。 


#define ngx_log error(level, lo0g, args...) 
If ((l10g)->log _ level >= level) ngx_log_error_core(level, log, args) 
#define ngx_log debug(level, lo0g, args...) \ 
if ((1og)->1og_level & level) \ 
ngx_log_error_core(NGX_LOG_ DEBUG, log, args) 
void ngx_l0og_error_core(ngx uint_t level, ngx_log t *1og，ngx_err t err, const 
char *fmt, ...); 


Nginx 的 日 志 模 块 记 录 日 志 的 核心 功能 是 由 ngx_log_error_core 方 法 
实现 的 ，ngx_log_error 宏 和 ngx_log_debug 宏 只 是 对 它 做 了 简单 的 封 
装 ， 一 般 情 况 下 记录 日 志 时 只 需要 使 用 这 两 个 宏 。 


ngx_log_error 安 和 ngx_log_debug 宏 都 包括 参数 level、log 、err、 


fmt， 下 面 分 别 解释 这 4 个 参数 的 意义 。 


(1) level 参 数 


对 于 ngx_log_error 安 来 说 ，level 表 示 当 前 这 条 日 志 的 级 别 。 它 的 取 
值 范围 见 表 4-6。 


表 4-6 ”ngx_log_error 日 志 接 口 level 参 数 的 取 值 范 


级 别名 称 
最 高 级 别 日 志 ， 日 志 的 内 容 不 会 再 写 入 log 参数 指定 的 文件 ， 而 是 会 直接 将 
日 志 输 出 到 标准 错误 设备 ， 如 控制 台 屏 幕 
大 于 NGX _ LOG _ ALERT 级 别 ， 而 小 于 或 等 于 NGX_LOG_EMERG 级 别 的 
日 志 都 会 输出 到 log 参数 指定 的 文件 中 


NGX LOG STDERR 


NGX LOG EMERG 


级 别名 称 
NGX LOG ALERT 
NGX LOG CRIT 
NGX LOG ERR 
NGX LOG WARN 
NGX LOG NOTICE 
NGX LOG INFO 
NGX LOG DEBUG 


没 
< 


大 于 NGX _ LOG _CRIT 级 别 

大 于 NGX _ LOG _ERR 级 别 

-于 NGX LOG_WARN 级 别 
大 于 NGX _ LOG NOTICE 级 别 
大 于 NGX _ LOG INFO 级 别 

大 于 NGX LOG _DEBUG 级 别 


调试 级 别 ， 最 低级 别 日 志 


才 


使 用 ngx_log_error 宏 记录 日 志 时 ， 如 果 传 入 的 level 级 别 小 于 或 等 于 
log 参 数 中 的 日 志 级 别 (通常 是 由 nginx.conf 配 置 文件 中 指定 ) ， 就 会 输 


出 日 志 内 容 ， 人 否则 这 条 日 志 会 被 忽略 。 


人 — 


在 使 用 ngx_log_debug 宏 时 ，level 的 意义 完全 不 同 ， 它 表达 的 意义 
不 再 是 级 别 (已 经 是 DEBUG 级 别 )y ， 而 是 日 志 类 型 ， 因 为 
ngx_log_debug 宏 记录 的 日 志 必 须 是 NGX_LOG_DEBUG 调 试 级 别 的 ， 
这 里 的 level 由 各 子 模块 定义 。level 的 取 值 范围 参见 表 4-7。 


表 4-7 ngx_log _ debug 日 志 接 口 level 参 数 的 取 值 苑 


级 别名 称 | 值 | 意 义 
NGX_LOG DEBUG CORE Nginx 核心 模块 的 调试 日 志 
NGX LOG DEBUG ALLOC Nginx 在 分 配 内 存 时 使 用 的 调试 日 志 
NGX LOG DEBUG MUTEX Nginx 在 使 用 进程 锁 时 使 用 的 调试 日 志 
NGX LOG DEBUG EVENT Nginx 事件 模块 的 调试 日 志 
NGX LOG DEBUG HTTP Nginx http 模块 的 调试 日 志 
NGX LOG DEBUG MAIL Neginx 邮件 模块 的 调试 日 志 
NGX LOG DEBUG _ MYSQL 表示 与 MySQL 相关 的 Nginx 模块 所 使 用 的 调试 日 志 


当 HTTP 模 块 调用 ngx_log_debug 宏 记录 日 志 时 ， 传 入 的 level 参 数 是 
NGX_ LOG_DEBUG_HTTP， 这 时 如 果 log 参 数 不 属于 HTTP 模块 ， 如 使 
用 了 event 事 件 模块 的 og， 则 不 会 输出 任何 日 志 。 它 正 是 ngx_log debug 
拥有 level 参 数 的 意义 所 在 。 


(2) log 参 数 


实际 上 ， 在 开发 HTTP 模 块 时 我 们 并 不 用 关心 log 参 数 的 构造 ， 因 为 
在 处 理 请 求 时 ngx_http_request_t 结 构 中 的 connection 成 员 就 有 一 个 
ngx_log t 类 型 的 log 成 员 ， 可 以 传 给 ngx_log_error 安 和 ngx_log_debug 安 
记录 日 志 。 在 读 取 配置 阶段 ，ngx_conf t 结 构 也 有 log 成 员 可 以 用 来 记录 
志 〈 读 取 配 置 阶段 时 的 日 志 信 息 都 将 输出 到 控制 台 屏 幕 ) 。 下 面 简 
单 地 看 一 下 ngx_log t 的 定义 。 


typedef struct ngx_1og_s ngx_log_t; 

typedef u_char *(*ngx_log handler_pt) (ngx_log t *1og，u_char *buf, size_t len); 

struct ngx_log _s { 
// 日 志 级 别 或 者 日 志 类 型 


ngx_uint_t log_level,; 
// 日 志文 件 


ngx_open_file_t *file; 


// 连接 数 ， 不 为 


0 时 会 输 虹 


到 日 志 中 


ngx_atomic uint_t connection; 


A/* 记 录 日 志 时 的 回调 方法 。 当 


handler 已 经 实现 (不 为 


NULL) ， 


DEBUG 调 试 


且 不 是 


级 别 时 ， 才 会 调 


handler 钧 子 方法 


*/ 


ngx_log_handler_pt handler; 


/* 每 


data 的 


data 参 


handlerks 


HTTP 框 架 就 定义 了 


个 模块 都 可 以 目 


使 


数 痢 


方法 。 通 常 ， 


定义 


是 在 实现 了 上 面 的 


调 方法 后 才 使 用 


handler 方 法 ， 并 在 


data 中 放 入 了 这 个 请 求 的 上 下 文 信息 ，i 


URI 输 昌 


WA 


的 。 例 如 ， 


上 到 


志 的 尾部 


void *data， 
/* 表 示 当 前 的 动作 。 实 际 上 ， 


action 与 


data 是 一 档 
handlerks 


HTTP 框 架 就 在 


的 ， 只 有 在 实现 了 


调 方法 后 才 会 使 


handler 方 法 中 检查 


action 是 否 为 
NULL， 如 果 不 为 


NULL， 就 会 在 日 志 后 加 入 “ 


while 


39 


用 。 例 如 ， 


这 


档 


每 次 输出 


志 时 都 会 


+action， 以 此 表示 当前 日 志 是 在 进行 什么 操作 ， 帮 助 定 位 问题 


*/ 


[ 旦 


这 个 请 求 


char *action; 


可 以 看 到 ， 如 果 只 是 想 把 相应 的 信息 记录 到 日 志文 件 中 ， 那 么 完 
全 不 需要 关心 ngx_log t 类 型 的 log 参 数 是 如 何 构造 的 。 特 别 是 在 编写 
HTTP 模 块 时 ，HTTP 框 架 要 求 所 有 的 HTTP 模 块 都 使 用 它 提供 的 log， 如 
果 重 定义 ngx_log_t 中 的 handler 方 法 ， 或 者 修改 data 指 向 的 地 址 ， 那 么 很 
可 能 会 造成 一 系列 问题 。 


然而 ， 从 上 文 对 ngx_log_t 结 构 的 接 述 中 可 以 看 出 ， 如 来 定义 一 种 
新 的 模块 〈 不 是 HITP 模 块 ) ， 那 么 日 志 模 块 提 供 很 强大 的 功能 ， 可 以 
把 一 些 通用 化 的 工作 都 放 到 handler 回 调 方 法 中 实现 。 


(3) er 参数 


err 人 参数 就 是 错误 码 ， 一 般 是 执行 系统 调用 失败 后 取得 的 errno 参 
数 。 当 err 不 为 0 时 ，Nginx 日 志 模 块 将 会 在 正常 日 志 内 容 前 输出 这 个 错 
翅 码 以 及 其 对 应 的 字符 哩 形式 的 错误 消 轧 。 


(4) fmt 参 数 


fmt 就 是 可 变 参数 ， 就 像 在 printf 等 C 语 言 方法 中 的 输入 一 样 。 例 
如 : 


ngx_log_error(NGX_LOG_ALERT，r->connection->10g0， 
"test_flag=%d, test_str=%V, path=%*s,mycf addr=%p", 
mycf->my_flag, 
&mycf->my_str, 
mycf->my_path->name.1en, 


mycf->my_path->name ,data， 
mycf ) ; 


fmt 的 大 部 分 规则 与 printf 等 通用 可 参 数 是 一 致 的 ， 然 而 Nginx 为 
了 方便 它 自 定义 的 数据 类 型 ， 重 新 实现 了 基本 的 ngx_vslprintf 方 法 。 例 
如 ， 增 加 了 诸如 %V 等 这 样 的 转换 类 型 ，%V 后 可 加 ngx_str_t 类 型 的 变 
量 ， 这 些 都 是 剖 通 的 printf 中 没有 的 。 表 4-8 列 出 了 ngx_vslprintf 中 文 持 
的 27 种 转换 格式 。 


@@ 注音 print 或 者 sprint 支 持 的 一 些 转换 格式 在 ngx_vslprintf 中 
是 不 支持 的 ， 或 者 意义 不 同 。 


表 4-8 打印 日 志 或 者 使 用 ngx_sprintf 系 列 方法 转换 字符 串 时 文 持 的 27 
种 转化 格式 


转换 格式 
9%0u 


%m 


9%X 


ox 


%. 


%f 


90 站 


os 


9%V 


ov 


%O 
%P 
%T 
SoM 
oz 
%oi 
%d 
%l 
%D 
%L 


%A 
or 


%p 
2%6c 
%7 
WN 
9%696 


用 法 

表示 无 符号 ， 其 后 还 可 以 跟 其 他 转换 符号 ， 如 %ui 表示 要 转换 的 类 型 是 ngx_uint_ t， 如 果 其 后 没有 
跟 转 换 符 号 ， 则 表示 要 转换 的 类 型 是 无 符号 十 进 制 正 数 

表示 以 最 大 长 度 来 转换 数字 类 击 (如 int) 

以 十 六 进 制 来 格式 化 转换 后 的 数据 。 注意 ， Nginx 中 的 %X 与 printf 等 转换 格式 完全 不 同 ， 它 只 是 
限制 转换 后 的 数字 以 十 六 进 制 格式 来 显示 而 不 是 限制 相应 参数 的 类 型 。 例如 , %Xd 后 跟着 int 类 型 , 
表示 以 十 六 进 制 格式 来 显示 int 整数 ， 而 %Xp 表示 以 十 六 进 制 格式 来 显示 指针 地 址 。 如 有 果 仅 有 %X， 
那么 是 没有 任何 输出 的 

%x 与 %X 的 用 法 完全 相同 ， 只 是 %X 以 A、B、C、D、E、F 表示 十 进 制 中 的 10、11、12、13、 
14、15， 而 %x 是 以 小 写 的 a、b、c、d、e、f{ 来 表示 

其 后 必须 紧 跟 数字 - 当前 实现 版 本 下 必须 与 %f 配合 使 用 ， 表 示 转 换 浮 点 数 时 小 数 部 分 的 位 数 。 例 
如 ，%.10f 表示 转换 double 类 型 时 ， 小数点 后 转换 且 必 须 转换 为 10 位 ,不 是 10 位 以 0 填补 

转换 double 类 型 数据 。 注 意 ， 它 与 printf 等 标准 C 语言 中 的 %f 完 全 不 同 ， 如 果 想 转换 小 数 部 分 ， 
则 必须 加 上 %.(number)if- 参见 本 表 中 %. 的 描述 

表示 要 转换 的 字符 长 度 。 目 前 仅 与 %s 配合 使 用 

转换 1 个 char* 或 者 u_char* 的 字符 串 。 与 %* 配合 使 用 时 ，%*s 表示 输出 指定 长 度 的 字符 串 ， 鞭 
后 必须 有 两 个 参数 : 表示 输出 字符 串 长 度 的 size_t 和 字符 串 地 址 char* 类 型 。 如 果 不 与 %* 配合 使 用 ， 
而 与 printf 等 标准 格式 相同 ， 那 么 字符 串 必须 以 “\0” 结尾 

转换 ngx_str 上 类 型 ，%V 对 应 的 参数 必须 是 ngx_str t 变量 的 地 址 。 它 将 会 按照 ngx_str t 类 型 的 
len 长 度 来 输出 data 字符 串 

转换 ngx_variable_value 1 类 型 ，%v 对 应 的 参数 必须 是 ngx_variable_value_t 变量 的 地 址 。 它 将 会 按 
腿 ngx_variable_value t 类 型 的 len 长 度 来 输出 data 字符 审 

转换 1 个 off t 类 地 

转换 1 个 ngx_pid_t 类 型 

转换 1 个 time_t 类 型 

转换 1 个 ngx_msec 【类 型 

转换 ssize 【类 型 数据 ， 如 果 用 %uz， 则 转换 的 数据 类 型 是 size 1 

转换 ngx_int t 型 数据 ， 如 果 用 %ui， 则 转换 的 数据 类 型 是 ngx_uint 1 

转换 int 型 数据 ， 如 果 用 %ud， 则 转换 的 数据 类 型 是 u_ int 

转换 long 型 数据 ， 如 果 用 %ul， 则 转换 的 数据 类 型 是 u_ long 

转换 int32 + 型 数据 ， 如 果 用 %uD， 则 转换 的 数据 类 型 是 uint32 + 

转换 int64 型 数据 ， 如 果 用 %ul， 则 转换 的 数据 类 型 是 uint64 1 

转换 ngx_atomic_int + 型 数据 ， 如 果 用 %uA， 则 转换 的 数据 类 型 是 ngx_atomic_uint t 

转换 1 个 rlim tt 类型。 系统 调用 getrlimit 或 者 setrlimit 时 都 会 使 用 rlim_t 类 型 参数 ， 它 实际 上 是 一 
个 算术 数据 类 型 ， 等 同 于 类 型 int、size 1 或 者 off t 

转换 1 个 指针 (地址 ) 

转换 1 个 字符 类 型 

表示 "0' 

表示 \n' 换行 符 ， 邮 "x0a"， 在 windows 操作 系统 上 则 表示 Win'， 也 就 是 wxOd\x0an 

打印 1 个 百 分 层 (% ) 


例如 ， 在 4.2.4 节 上 自 定 义 的 ngx_conf_set_myconfig 方 法 中 ， 可 以 这 样 
输出 日 志 。 


long tl = 


u_long tul = 


int32_t ti 
ngx_str_t 
double tdo 


4900000000， 
5000000000， 
32 = 110; 
tstr = ngx_string("teststr"); 
ub = 3.1415926535897932， 


int x = 15; 


ngx_1log_er 


ror (NGX_LOG_ALERT, cf->l0g, 0, 


"1=%], ul=%ul1, D=%D, p=%p, f=%.10f, str=%V, x=%xd, X=%Xd", 


tl1, tul, ti32,&ti32,tdoub,&tstr, x,x); 


这 上 段 代码 将 会 输出 : 


nginx: [al 


ert] 


1=49000000009, ul=5000000000,D=110, p=00007FFFF26B36DC, f=3.1415926536, str=teststr,x=f 


,X=F 


在 Nginx 的 许多 核心 模块 中 可 以 看 到 ， 


级 别 的 日 志 接 口 ， 见 表 4-9 。 


表 4-9 Nginx 提 供 的 不 \ 文 持 可 变 参 


日 志 接口 
ngx log debug0 
ngx log debugl 
ngx log debug2 
ngx log debug3 
ngx log debug4 
ngx log debug5 
ngx log debug6 


~ 


nex log debueg”7 


ngx log debug8 


ngx log debugO(level. 
ngx log debugl(level. 
ngx log debug2(level, 
ngx log debug3(level. 
ngx log debug4(level. 
ngx log debug5(level. 


ngx log debug6(level. 


它们 多 使 用 的 是 debug 调 试 


数 的 调试 日 志 接 口 


使 用 参数 


有 
g, err, 
本 
&、eIT. 
g. err, 
g, eIt, 


g, ert, 


fmt) 

fmt, argl) 

fmt., argl, arg2 

fnmt, argl, arg2. arg3) 

fmt. argl, arg2. arg3, arg4) 

fimt, argl, arg2. arg3, arg4. arg5) 


fmt. argl, arg2. arg3, arg4. arg5, arg6) 


fmt 格式 后 只 接受 参数 ngx log debug7(level, log, err, fimt, argl, arg2, arg3, arg4, arg5, arg6, arg7) 


fmt 格式 后 上 


arg7. arg8) 


ngx_log debug8(level. log, err, fmt. argl, arg2. arg3, arg4, arg5. arg6, 


4.5 ”请 求 的 上 下 文 


在 Nginx 中 ， 上 下 文 有 很 多 种 合 义 ， 然 而 本 市 描述 的 上 下 文 是 指 
HTTP 框 染 为 每 个 HTTP 请 求 所 准备 的 结构 体 。HTTP 框 架 定义 的 这 个 上 
下 文 是 针对 于 HTTP 请 求 的 ， 而 且 一 个 HTTP 请 求 对 应 于 每 一 个 HTTP 模 
块 都 可 以 有 一 个 独立 的 上 下 文 结构 体 (并 不 是 一 个 请 求 的 上 下 文 由 所 
有 HTTP 模 块 共用 ) 。 


4.5.1 ”上下文 与 全 异步 Web 服 务 絮 的 天 系 


上 下 文 是 什么 ? 简单 地 讲 ， 束 是 在 一 个 请 求 的 处 理 过 程 中 ， 用 类 
似 struct 这 样 的 结构 体 把 一 些 关 键 的 信息 都 保存 下 来 ， 这 个 结构 体 可 以 
称 为 请 求 的 上 下 文 。 每 个 HTTP 模 块 都 可 以 有 上 自己 的 上 下 文 结构 体 ， 一 
般 都 是 在 刚 开 始 处 理 请 求 时 在 内 存 池 上 分 配 它 ， 之 后 当 经 由 epoll、 
HTTP 框 架 再 次 调用 到 HTTP 模 块 的 处 理 方法 时 ， 这 个 HTTP 模 块 可 以 由 
请 求 的 上 下 文 结构 体 中 获取 信息 。 请 求 结束 时 就 会 销毁 该 请 求 的 内 存 
池 ， 目 然 也 就 销毁 了 上 下 文 结构 体 。 以 上 束 是 HTTP 请 求 上 下 文 的 使 用 
场景 ， 由 于 1 个 上 下 文 结构 体 是 仅 对 1 个 请 求 1 个 模块 而 言 的 ， 所 以 它 是 
低 耦 合 的 。 如 果 这 个 模块 不 需要 使 用 上 下 文 ， 也 可 以 完全 不 理会 HTTP 
上 下 文 这 个 概念 。 


那么 ， 为 什么 要 定义 HTTP 上下文 这 个 概念 呢 ? 因为 Nginx 和 是 个 强 
大 的 全 异步 处 理 的 web 服务器 ， 和 意味 着 1 个 请 求 并 不 会 在 epoll 的 1 次 调 
度 中 人 处 理 完成 ， 甚 至 可 能 成 千 上 万 次 的 调度 各 个 HTTP 模 块 后 才能 完成 
请 求 的 处 理 。 


怎么 理解 上 面 这 句 话 呢 ? 以 Apache 服 务 器 为 例 ，Apache 就 像 某 些 
高 档 餐 厅 ， 每 位 客人 (HTTP 请 求 ) 都 有 1 位 服务 员 (一 个 Apache 进 
程 ) 全 程 服 务 ， 每 位 服务 员 只 有 从 头 至 尾 服务 完 这 位 客人 后 ， 才 能 去 
为 下 一 个 客人 提供 服务 。 因 此 和 餐厅 的 并 发 处 理 数 量 受 制 于 服务 员 的 数 
， 但 服务 员 的 数量 也 不 是 越 多 越 好 ， 因 为 餐厅 的 固定 设施 (CPU) 
是 有 限 的 ， 它 的 管理 成 本 (Linux 内 核 的 进程 切换 成 本 ) 也 会 随 着 服务 
员 数 量 的 增加 而 提高 ， 最 终 影响 服务 质量 。Nginx 则 不 同 ， 它 束 像 
Playfirst 公 司 在 2005 年 发 布 的 休闲 游戏 《美女 餐厅 》 一 样 ，1 位 服务 员 
同时 处 理 所 有 客人 的 需求 。 当 1 位 客人 进入 餐厅 后 ， 服 务 员 首先 给 它 安 
排 好 架子 并 把 末 单 给 客人 后 束 离 开 了 ， 继 续 服 务 于 其 他 客人 。 当 这 位 
客人 决定 点 哪些 菜 后 ， 束 试图 去 叫 服务 员 过 来 处 理 点 呈 需 求 ， 当 然 ， 
服务 员 可 能 正在 忙于 其 他 客人 ,但 只 要 一 有 空间 束 会 过 来 拿 羔 单 并 交 
给 厨房 ， 再 去 服务 于 其 他 客人 。 直 到 厨房 通知 这 位 客人 的 茉 已 世人 鱼 完 
毕 ， 服 务 员 再 取 来 琳 主 动 地 传递 给 客人 ， 请 他 用 和 餐 ， 之 后 服务 员 叉 去 
寻找 是 否 有 其 他 客人 在 等 待 服务 。 


wl 


可 以 注意 到 ， 当 1 位 客人 进入 Nginx“ 和 餐厅 ”时 ， 首 先是 由 客人 来 “ 激 
活 ?Nginx“ 服 务 员 ” 的 。Nginx“ 服 务 员 ”再 次 来 处 理 这 位 客人 的 请 求 时 ， 
有 可 能 是 因为 这 位 客人 点 完全 后 大 声 地 叫 Nginx“ 服 务 员 ”， 等 候 她 来 服 
务 ， 也 有 可 能 是 因为 厨房 做 好 沫 后 厨师 “ 油 活 ?了 这 位 客人 的 服务 ， 也 
吕 是 说 “激活 ?Nginx“ 服 务 员 ”的 对 象征 不 辐 定 的 。 和 餐厅 的 流程 是 先 点 
环 ， 再 上 沫 ， 最 后 收 账单 以 及 撤 碗 盘 ， 但 客人 十 不 想 了 解 这 个 流程 
的 ， 所 以 Nginx“ 服 务 员 ”需要 为 每 位 客人 建立 上 下 文 结构 体 来 表示 客人 
进行 到 哪个 步 又， 即 他 点 了 哪些 荣 、 目 前 已 经 上 了 哪些 荣 ， 这 些 信息 
都 需要 独立 的 保存 。“ 服 务 员 ” 不 会 去 记 住所 有 客人 的 “上 下 文 信息 ”， 
因为 要 同时 服务 的 客人 可 能 很 多 ， 只 有 在 服务 到 茶 位 客人 时 才 会 去 得 
对 应 的 “上 下 文 信息 ”。 


上 面 说 的 Nginx“ 服 务 员 ”就 像 Nginx worker 进 程 ， 客 人 就 是 一 个 个 
请 求 ， 一 个 Nginx 进 程 同时 可 以 处 理 百 万 级 别 的 并 发 HTTP 请 求 。 厨 房 
这 些 设施 可 能 是 网 卡 、 硬 盘 等 便 件 。 因 此 ， 如 采 我 们 开发 的 HTTP 模块 
会 多 次 反复 处 理 同 1 个 请 求 ， 那 么 必须 定义 上 下 文 结构 体 来 保存 处 理 过 
程 的 中 间 状 态 ， 因 为 谁 也 不 知道 下 一 次 是 由 网 卡 还 是 便 开 等 服务 来 激 
活 Nginx 进 程 继续 处 理 这 个 请 求 。Nginx 框 架 不 会 维护 这 个 上 下 文 ， 只 
能 由 这 个 请 求 目 己 保存 着 上 下 文 结构 体 。 


再 把 这 个 例子 对 应 到 HTTP 框 架 中 。 点 菜 可 能 是 一 件 非常 复杂 的 
事 ， 因 为 可 能 涉及 深 末 、 热 采 、 淘 、 甜 品 等 。 假 如 HTTP 模 块 A 负责 深 


来 、HTTP 模 块 B 负 责 热 薪 、HTTP 模 块 C 负 责 汤 。 当 一 位 新 客人 到 来 
后 ， 他 招呼 着 服务 员 (worker 进 程 ， 和 HTTP 框 架 处 理 他 的 点 菜 需 求 时 
〈 假 设 他 想 点 2 个 凉菜 、5 个 热 菜 、1 个 汤 ) ，HTTP 模 块 A 刚 处 理 了 1 个 
头 琳 ， 又 有 其 他 客人 将 服务 员 叫 走 了 ， 那 么 ， 这 个 客人 处 必须 有 一 张 
纸 记 隶 着 天 于 凉菜 刚 点 了 一 个 ， 另 一 张 纸 记 隶 着 热 沫 一 个 没 点 ， 由 于 
HTTP 模 块 C 知 道 ， 当 前 的 餐厅 汤 已 经 卖 完 ， 业 务实 在 是 太 简 单 了 ( 回 
顾 一 下 第 3 章 的 helloword 例 子 ) ， 所 以 不 需要 再 有 一 张 纸 记 录 着 淘 有 
没有 点 。 这 两 张 纸 只 从 属于 这 个 客人 ， 对 于 其 他 客人 没有 意义 ， 这 整 
征 上 面 所 说 的 ， 上 下 文 只 是 对 于 一 个 请 求 而 言 。 同 时 ， 每 个 HTTP 模 块 
都 可 以 拥有 记录 客人 (请求) 状态 的 纸 ， 这 张 纸 就 其 实 就 是 上 下 文 结 
构 体 。 当 这 个 客人 叫 来 服务 员 时 ， 各 个 HTTP 模块 可 以 查看 客人 吴 前 的 
两 张 纸 ， 了 人 解 到 点 了 哪些 菜 ， 这 才 可 以 继续 处 理 下 去 。 


在 第 3 章 中 的 例子 中 虽然 没有 使 用 到 上 下 文 ， 但 也 完成 了 许多 功 
能 ， 这 是 因为 第 3 章 中 的 mytest 模 块 对 同 1 个 请 求 只 处 理 了 一 次 (发 送 
员 应 包 时 虽然 有 许多 次 调用 ， 但 这 些 调用 是 由 HTTP 框 架 大 助 我 们 完成 
的 ， 并 没有 再 次 回调 mytest 模 块 中 的 方法 ) ， 它 的 功能 非常 简单 。 在 
第 5 章 中 可 以 看 到 ， 无 论 是 subrequest 还 是 upstream， 都 必须 有 上 下 文 结 
构 体 来 支持 异步 地 访问 第 三 方 服务 。 


4.5.2 ”如 何 使 用 HTTP 上 下 文 


ngx_http_get_module_ctx 和 ngx_http_set_ctx 这 两 个 宏 可 以 完成 
HTTP 上 下 文 的 设置 和 使 用 。 先 看 看 这 两 个 宏 的 定义 ， 如 下 所 示 。 


#define ngx_http_get module ctx(r, module) (r)->ctx[module.ctx_ index] 
#define ngx_http_set_ctx(r, c, module) r->ctx[module.ctx_index] = c; 


ngx_http_get_module_ctx 接 受 两 个 参数 ， 其 中 第 1 个 参数 是 
ngx_http_request_t 指 针 ， 第 2 个 参数 则 是 当前 的 HTTP 模 块 对 象 。 例 
如 ， 在 mytest 模 块 中 使 用 的 就 是 在 3.5 节 中 定义 的 ngx_module t 类 型 的 
ngx_http_mytest_module 结 构 体 。ngx_http_get_module_ctx 返 回 值 就 是 
某 个 HTTP 模 块 的 上 下 文 结构 体 指针 ， 如 果 这 个 HTTP 模 块 没 有 设置 过 
上 上 下文， 那么 将 会 返回 NULL 空 指针 。 因 此 ， 在 任何 一 个 HTTP 模 块 
中 ， 都 可 以 使 用 ngx_http_get_module_ctx 获 取 所 有 HTTP 模 块 为 该 请 求 
创建 的 上 下 文 结构 体 。 


ngx_http_set_ctx 接 受 3 个 参数 ， 其 中 第 1 个 参数 是 
ngx_http_request_t 指 针 ， 第 2 个 参数 是 准备 设置 的 上 下 文 结构 体 的 指 
针 ， 第 3 个 参数 则 是 HITP 模 块 对 象 。 


举 个 简单 的 例子 来 说 明 如 何 使 用 ngx_http_get_ module_ctx 安 和 
ngx_http_set_ctx 安 。 首 移 建立 mytest 模 块 的 上 下 文 结构 体 ， 如 
ngx_http_mytest ctx t。 

typedef Struct 区 


ngx_uint_t my_step， 
} ngx_http_mytest ctx_t; 


当 请 求 第 1 次 进入 mytest 模 块 处 理 时 ， 创 建 ngx_http_mytest_ctx_t 结 
构 体 ， 并 设置 到 这 个 请 求 的 上 下 文中 。 


static ngx_int_t 
ngx_http_mytest_handler(ngx_http_request _t *r) 
{ 


// 首先 调用 


ngx_http_get_module_ctx 宏 来 获取 上 下 文 结构 体 


ngx_http_mytest_ctx_t* myctx = 
ngx_http_get module ctx(r,ngx_http_mytest module); 
// 如 果 之 前 没有 设置 过 上 下 文 ， 那么 应 当 返 回 


NULL 
if (myctx == NULL) 


/* 必 须 在 当前 请 求 的 内 存 池 
r->poo1 中 分 配 上 下 文 结构 体 ， 这 样 请 求 结束 时 结构 体 占 用 的 内 存 才 会 释放 


* 

/ 
myctx = ngx_palloc(r->pool, sizeof(ngx_http_mytest_ ctx_t)); 
if (myctx == NULL) 
{ 


return NGX_ERROR; 


} 
// 将 刚 分 配 的 结构 体 设置 至 


| 此 


前 请 求 的 上 下 文中 


ngx_http_set_ctx(r,myctx,ngx_http_mytest_module); 


} 
// 之 后 可 以 任意 使 用 


myctx 这 个 上 下 文 结构 体 


如 宁 Nginx 多 次 回调 mytest 模 块 的 相应 方法 ， 那 么 每 次 用 
ngx_http_get_module_ctx 宏 取 到 上 下 文 ，ngx_http_mytest_ctx_t 都 可 以 
正常 使 用 ，HTTP 框 架 可 以 对 一 个 请 求 保 证 ， 无 论调 用 多 少 次 
ngx_http_get_module_ctx 宏 都 只 取 到 同一 个 上 下 文 结构 。 


4.5.3 HITTP 框 架 如 何 维护 上 下 文 结构 


首先 看 一 下 ngx_http_request_t 结 构 的 ctx 成 员 。 


struct ngx_http_request_Ss { 


void **ctx; 


可 以 看 到 ，ctx 与 4.3.2 方 中 ngx_http_conf_ctx_t 结 构 的 3 个 数组 成 员 
非常 相似 ， 它 们 都 表示 指向 void* 指 针 的 数组 。HTTP 框 架 束 是 在 ctx 数 
组 中 保存 所 有 HTTP 模 块 上 下 文 结构 体 的 指针 的 。 


HTTP 框 架 在 开始 处 理 1 个 HITP 请 求 时 ， 会 在 创建 
ngx_http_request_t 结 构 后 ， 建 立 ctx 数 组 来 存储 所 有 HTTP 模 块 的 上 下 文 
结构 体 指针 (请 求 ngx_http_request_t 的 ctx 成 员 是 一 个 指针 数组 ， 其 初 
始 化 详 见 图 11-2 的 第 9 步 ) 。 


r->ctx = ngx_pcalloc(r->pool, sizeof(void*)*ngx_http_max_module); 
if (r->ctx == NULL) { 

ngx_destroy_pool(r->pool); 

ngx_http_close_connection(c); 

return; 


} 


对 比 4.5.2 方 中 的 两 个 宏 的 定义 可 以 看 出 ，ngx_http_get_module_ctx 
和 ngx_http_set_ctx 只 是 去 获取 或 者 设置 ctx 数 组 中 相应 HTTP 模 块 的 指 
针 而 已 。 


4.6 ”小 结 


通过 第 3 草 ， 我 们 已 经 了 解 到 开发 一 个 基本 的 HTTP 模 块 可 以 非常 
人 简单， 而 本 章 介 绍 的 读 取 配置 项 、 使 用 日 志 记 杂 必 要 信息 、 为 每 个 
HTTP 请 求 定 义 上 下 文 则 十 开发 功能 灵活 、 复 杂 、 高 性 能 的 Nginx 模 块 
时 必须 了 解 的 机 制 。 熟练 掌握 本 草 内 容 ， 是 开发 每 一 个 产品 级 别 HTTP 
模块 的 先决 条 件 。 


第 5 章 ”访问 第 三 方 服务 


当 需 要 访问 第 三 方 服务 时 ，Nginx 提 供 了 两 种 全 异步 方式 来 与 第 三 
方 服务 器 通信 : upstream 与 subrequest。upstream 可 以 保证 在 与 第 三 
服务 器 交互 时 (包括 三 次 握手 建立 TCP 连 授 、 发 送 请 求 、 接 收 啊 应 、 
四 次 握手 关闭 TCP 连 接 等 ) 不 会 阻塞 Nginx 进 程 处 理 其 他 请 求 ， 也 就 是 
说 ，Nginx 仍 然 可 以 保持 它 的 高 性 能 。 因 此 ， 在 开发 HTTP 模 块 时 ， 如 
采 需 要 访问 第 三 方 服务 是 不 能 目 己 简 单 地 用 套 接 字 编程 实现 的 ， 这 样 
会 破坏 Nginx 优 秀 的 全 异步 架构 。subrequest 只 是 分 解 复杂 请 求 的 一 种 
设计 模式 ， 它 本 质 上 与 访问 第 三 方 服务 没有 任何 关系 ， 但 从 HTTP 模 块 
开发 者 的 角度 而 言 ， 使 用 subrequest 访 问 第 三 方 服务 却 很 常用 ， 当 然 ， 
subrequest 访 问 第 三 方 服 务 最 终 也 是 基于 upstream 实 现 的 。 这 两 种 机 制 
是 HTTP 框 架 为 用 户 准 备 的 、 无 阻 吾 访问 第 三 方 服务 的 利 絮 。 


upstream 和 subrequest 的 设计 目标 是 完全 不 同 的 。 从 名 称 中 可 以 看 
出 ，upstream 补 定义 为 访问 上 游 服务 器 ， 也 束 是 说 ， 它 把 Nginx 定 义 为 
代理 服务 器 ， 上 前 要 功能 是 透 传 ， 其 次 才 是 以 TCP 获 取 第 三 方 服务 屁 的 
内 容 。Nginx 的 HTTP 反 回 代 理 模块 融 是 基于 upstream 方 式 实现 的 。 顾 
名 思 义 ，subrequest 征 从 属 请 求 的 意思 ， 在 这 里 我 们 更 倾 癌 于 称 它 为 子 
请 求 ， 也 殉 是 说 ，subrequest 将 会 为 客户 请 求 创建 子 请 求 ， 这 是 为 什么 
呢 ? 因 为 异步 无 阻塞 程序 的 开发 过 于 复杂 ， 所 以 HTTP 框 架 提 供 了 这 种 


机 制 将 一 个 复杂 的 请 求 分 解 为 多 个 子 请 求 ， 每 个 子 请 求 负 贡 一 种 功 
能 ， 而 最 初 的 原始 请 求 负 责 构成 并 发 送 啊 应 给 客户 端 。 例 如 ， 用 
subrequest 访 问 第 三 方 服务 ， 一 般 都 是 派生 出 子 请 求 访问 上 游 服务 器 ， 
父 请 求 在 完全 取得 上 游 服 务 器 的 响应 后 再 决定 如 何 处 理 来 自 客户 端的 
请 求 。 这 样 做 的 好 处 是 每 个 子 请 求 专 注 于 一 种 功能 。 例 如 ， 对 于 一 个 
子 请 求 ， 通 常 在 NGX_HTTP_CONTENT_PHASE 阶 段 仅 会 使 用 一 个 
HTTP 模 块 处 理 ， 这 大 大 降低 了 模块 开发 的 复杂 度 。 从 HTTP 框 染 的 内 
部 来 说 ，subrequest 与 upstream 也 完全 不 同 ，upstream 是 从 属于 用 户 请 
求 的 ，subrequest 与 原始 的 用 户 请 求 相 比 是 一 个 (或 多 个 ) 独立 的 新 请 
求 ， 只 是 新 的 子 请 求 与 原始 请 求 之 间 可 以 并 发 的 处 理 。 


因此 ， 当 我 们 希望 把 第 三 方 服务 的 内 容 几 乎 原封 不 动 地 返回 给 
户 时 ， 一 般 使 用 upstream 方 式 ， 它 可 以 非常 高 效 地 透 传 HITP (第 12 章 
详细 描述 了 upstream 机 制 的 两 种 透 传 方式 ) 。 可 如 果 我 们 访问 第 三 
服务 只 是 为 了 获取 某 些 信息 ， 再 依据 这 些 信息 来 构造 啊 应 并 发 送 给 用 
户 ， 这 时 应 该 用 subrequest 方 式 ， 因 为 从 业务 上 来 说 ， 这 是 两 件 事 : 获 
取 上 游 啊 应 ， 再 根据 啊 应 内 容 处 理 请 求 ， 应 由 两 个 请 求 处 理 。 


本 章 仍 然 以 mytest 模 块 为 例 进 行 说 明 ， 但 会 扩展 mytest 的 功能 。 注 
意 ， 文 中 没有 提 及 的 代码 (如 定义 mytest 模 块 ) 都 与 第 3 章 完全 相同 。 


5.1 _ upstream 的 使 用 方式 


Nginx 的 核心 功能 一 一 反 向 代理 是 基于 upstream 模 块 (该 模块 属于 
HTTP 框 染 的 一 部 分 实现 的 。 在 弄 清 楚 upstream 的 用 法 后 ， 完 全 可 以 
根据 自己 的 需求 重 写 Nginx 的 反 向 代理 功能 。 例 如 ， 反 癌 代理 模块 是 在 
先 接收 完 客 户 请 求 的 HTTP 包 体 后 ， 才 向 上 游 服 务 器 建立 连接 并 转发 请 
求 的 。 假 设 用 户 要 上 传 大 小 为 1GB 的 文件 ， 由 于 网 速 限制 ， 文 件 完整 
地 到 达 Nginx 需 要 10 小 时 ， 恰 巧 Nginx 与 上 洲 服 务 器 间 的 网 络 也 很 差 

(当然 这 种 情况 很 少见 ) ， 反 向 代理 这 个 请 求 到 上 游 服 务 也 需要 10 小 
时 ， 因 此 ， 根 据 用 户 的 网 速 也 许 本 来 只 要 10 个 小 时 的 上 传 过 程 ， 最 终 
可 能 需要 20 个 小 时 才能 完成 。 在 了 解 了 upstream 功 能 后 ， 可 以 试 着 改变 
反 回 代理 模块 的 这 种 特性 ， 比 如 模仿 squid 反 回 代 理 模 式 ， 在 接收 完整 
HTTP 请 求 的 头 部 后 就 气 上 游 服务 器 建立 连接 ， 并 开始 将 请 求 向 上 游 服 


务 郁 透 传 。 


upstream 的 使 用 方式 并 不 复杂 ， 它 提供 了 8 个 回调 方法 ， 用 户 只 需 
要 视 自己 的 需要 实现 其 中 几 个 回调 方法 就 可 以 了 。 在 了 解 这 8 个 回调 方 
法 之 前 ， 首 先 要 了 解 upstream 是 如 何 嵌 入 到 一 个 请 求 中 的 。 


从 第 3 章 中 的 内 容 可 以 看 到 ， 模 块 在 处 理 任何 一 个 请 求 时 都 有 
ngx_http_request_t 结 构 的 对 象 r， 而 请 求 r 中 又 有 一 个 


ngx_http_upstream_t 类 型 的 成 员 upstream 。 


typedef struct ngx_http_request_s ngx_http_request_t; 
struct ngx_http_request_s { 


ngx_http_upstream 七 *upstream; 


如 有 果 没 有 使 用 upstream 机 制 ， 那 么 ngx_http_request_t 中 的 upstream 
成 员 是 NULL 空 指针 ， 如 果 使 用 upstream 机 制 ， 那 么 关键 在 于 如 何 设置 


r->upstream 成 员 。 


图 5-1 列 出 了 使 用 HTTP 模 块 启用 upstream 机 制 的 示意 图 。 下 面 以 
mytest 模 块 为 例 人 简单 地 解释 一 下 图 5-1。 


1) 首先 需要 创建 上 面 介 绍 的 upstream 成 员 ， 注 意 ，upstream 在 初始 
状态 下 是 NULL 空 指针 。 可 以 调用 HTTP 框 架 提 供 好 的 


ngx_http_upstream_create 方 法 来 创建 upstream 。 


2) 接 春 设置 上 游 服 务 器 的 地 址 。 在 HTTP 反 向 代理 功能 中 似乎 只 
能 使 用 在 nginx.conf 中 配置 好 的 上 游 服 务 紫 (参见 2.5 太 的 upstream 配 置 
块 内 容 ) ， 而 实际 上 upstream 机 制 并 没有 这 种 要 求 ， 用 户 能 够 以 任意 方 
式 指定 上 游 服 务 右 的 IP 地 址 。 例 如 ， 可 以 从 请 来 的 URL 或 HTTP 头 部 中 
动态 地 获取 上 游 服务 器 地 址 ，ngx_http_upstream_t 中 的 resolved 成 员 就 
可 以 帮助 用 户 设置 上 游 服务 器 ( 详 见 5.1.3 节 ) 


3) 由 于 upstream 非 常 灵活 ， 在 各 个 执行 阶段 中 都 会 试图 回调 使 用 
它 的 HTTP 模 块 实现 的 8 个 方法 ( 详 见 5.1.4 市 ) ， 因 此 ， 在 mytest 模 块 例 
子 中 ， 用 户 要 定义 好 这 些 回调 方法 。 


4) 在 mvytest 模 块 中 ， 调 用 ngx_http_upstream_init 方 法 即 可 启动 
upstream 机 制 。 注 意 ，ngx_http_mytest_handler 方 法 此 时 必须 返回 
NGX_DONE， 这 是 在 要 求 HTTP 框 架 不 要 按 阶段 继续 向 下 人 处 理 请 求 
了 ， 同 时 它 告诉 HTTP 框 架 请 求 必 须 停 留 在 当前 阶段 ， 等 待 基 个 HTTP 
模块 主动 地 继续 处 理 这 个 请 求 〈 例 如 ， 在 上 游 服务 器 主动 关闭 连接 
时 ，upstream 模 块 就 会 主动 地 继续 处 理 这 个 请 求 ， 很 可 能 会 同 客户 病 发 
送 502 响 应 码 ) 


调用 nsx http _ upstream _create 方法 为 请 求 创建 upstream 


设置 第 三 方 服务 大 的 地 址 


设置 的 回调 方法 


YY 
) 


洞 用 ngx _http_upstream _init 方法 司 动 upstream 


图 5-1 ”启动 upstream 的 流程 图 


使 用 upstream 模 块 提供 的 ngx_http_upstream_init 方 法 后 ，HTTP 框 架 
到 底 如 何 和 运行 upstream 机 制 呢 ? 图 5-2 给 出 了 一 个 常见 的 upstream 执 行 示 
意图 ， 它 仅 在 概念 上 表示 主要 流程 ， 与 代码 的 执行 没有 关系 。 第 12 章 
将 详细 介绍 upstream 机 制 到 底 是 如 何 执行 的 。 


图 5-2 所 示 的 upstream 流 程 包 含 了 epoll 模 块 多 次 调度 、 处 理 一 个 请 
求 的 过 程 ， 它 虽然 与 实际 代码 执行 天 系 不 大 ， 但 却 指出 了 最 第 用 的 3 个 
回调 方法 
调 的 。 


create_request、Pprocess_header、finalize_request 是 如 何 回 


回调 create _request 方法 创建 发 往 上 游 的 请 求 


用 无 阻塞 套 接 字 建立 TCP 连 接 并 等 待 建立 成 功 
[ 等 待 上 游 服务 器 的 SYN ACK 包 ] 

[ TCP 连接 建立 成 功 ] 
发 送 请 求 到 第 三 方 服务 
[未 发 送 完全 部 请 求 ] 
[ 发 送 完全 部 请 求 ] 


接收 第 三 方 服务 返回 的 包头 


回调 process _header 方 法 处 理 包 头 


[未 接收 到 完整 包头 ] 


[ 接收 到 完整 包头 ] 


处 理 第 三 方 服务 返回 的 包 体 
[ 上 游 服务 器 还 在 发 送 包 体 ] 


二 


[接收 、 处 理 完 全 部 的 包 体 ] 


调 finalize _request 并 销毁 请 求 


图 5-2 upstream 执 行 的 一 般 流程 


@ 注意 upstream 提 供 了 3 种 处 理 上 游 服 务 右 包 体 的 方式 ， 包 括 
交 由 HTTP 模 块 使 用 input_filter 回 调 方法 直接 人 处理 包 体 、 以 固定 缓冲 区 
转发 包 体 、 以 多 个 绥 冲 加 磁 副 文件 的 方式 转发 包 体 等 。 在 后 两 种 转发 
包 体 的 方式 中 ，upstream 还 与 文件 绥 存 功能 紧密 相关 ， 但 为 了 让 大 家 更 
清晰 地 理解 upstream， 本 章 中 将 不 涉及 文件 缓存 。 


5.1.1 ngx_http_upstream_t 结 构 体 


上 面 了 解 了 upstream 机 制 运 行 的 主要 流程 ， 现 在 来 看 一 下 
ngx_http_upstream_t 结 构 体 。ngx_http_upstream_t 结 构 体 里 有 些 成 员 仅 
仅 是 在 upstream 模 块 内 部 使 用 的 ， 这 里 就 不 一 一 列 出 了 〈 由 于 C 语 言 是 
面 癌 过 程 语言 ， 所 以 ngx_http_upstream_t 结 构 体 里 会 出 现 第 三 方 HITP 
模块 并 不 关心 的 成 员 。 在 12.1.2 世 中 会 完整 地 介绍 ngx_http_upstream t 
中 的 所 有 成 员 ) 。 


typedef struct ngx_http_upstream_s ngx_http_upstream t; 
struct ngx_http_upstream_s { 


/*request_bufs 决 定 发 送 什 么 样 的 请 求 给 上 游 服 务 器 ， 在 实现 


create_request 方 法 时 需要 设置 它 


«ff 
ngx_chain_t *request_bufs; 
// upstream 访 问 时 的 所 有 限制 性 参数 ， 在 


5.1.2 节 会 详细 讨论 它 


ngx_http_upstream conf_t *conf; 
// 通过 


resolved 可 以 直接 指定 上 游 服 务 器 地 址 ， 在 


5.1.3 节 会 详细 讨论 它 


ngx_http_upstream_resolved t *resolved 


/*buffer 成 员 存储 接收 自 上 游 服务 器 发 来 的 响应 内 容 ， 由 于 它 会 被 复 用 ， 所 以 具有 下 列 多 种 意义 : 


al) 在 使 
process_header 方 法 解析 上 游 响 应 的 包头 时 ， 
buffer 中 将 会 保存 完整 的 响 人 


b) 当 下 面 的 


图 
加 


buffering 成 员 为 


1， 而 且 此 时 
upstream 是 向 下 游 转发 上 游 的 包 体 时 ， 


buffer 没 有 意义 ; 


Cc) 当 


buffering 标 志 位 为 
0 时， 


buffer 绥 冲 区 会 被 用 于 反复 地 接收 上 游 的 包 体 ， 进 而 向 下 游 转发 ; 


d) 当 
upstream 并 不 用 于 转发 上 游 包 体 时 ， 
buffer 会 被 用 于 反复 接收 上 游 的 包 体 ， 


HTTP 模 块 实现 的 


input_filter 方 法 需要 关注 它 


*/ 
ngx_buf_t buffer; 
// 构造 发 往 上 游 服务 器 的 请 求 内 容 


ngx_int_t (*create_ request)(ngx_http_request t *r); 
/* 收 到 上 游 服务 器 的 响应 后 就 会 回调 


process_header 方 法 。 如 果 


process_header 返 回 


NGX_AGAIN， 那 么 是 在 告诉 


Upstream 还 没有 收 到 完整 的 响应 包头 ， 此 时 ， 对 于 本 次 


upstream 请 求 来 说 ， 再 次 接收 到 上 游 服 务 器 发 来 的 


TCP 流 时 ， 还 会 调用 


process_header 方 法 处 理 ， 直 到 


process_header 函 数 返回 非 


NGX_AGAIN 值 这 一 阶段 才 会 停止 


*/ 


upstream 请 求 时 调用 


ngx_int t (*process_ header)(ngx_http_request t *r); 
// 销毁 


void (*finalize request)(ngx_http_request t *r, 
ngx_int_t rc); 


// 5 个 可 选 的 回调 方法 


ngx_int_t (*input_filter_init)(void *data); 
ngx_int_t (*input_filter)(void *data, ssize t bytes); 
ngx_int t (*reinit request)(ngx_http_request t *r); 
void (*abort_request)(ngx_http_request t *r); 
ngx_int_t (*rewrite redirect)(ngx_http_request t *r, 
ngx_table elt t *h, size t prefix); 


// 是 否 基 于 
SSL 协 议 访问 上 游 服 务 器 
unsigned ssl:1; 
/* 在 向 客户 端 转发 上 游 服 务 器 的 包 体 时 才 有 用 。 当 
buffering 为 
1 时 ， 表 示 使 用 多 个 缓冲 区 以 及 磁 强 文件 来 转发 上 游 的 响应 包 体 。 当 


Nginx 与 上 游 间 的 网 速 远大 于 


Nginx 与 下 游客 户 端 则 的 网 速 时 ， 让 


Nginx 开 辟 更 多 的 内 存 甚至 使 用 磁盘 文件 
压力 。 当 


T 


buffering 为 


9 时 ， 


示 只 使 上 再 的 这 二 个 


buffer 缓 冲 区 来 向 下 游 转发 响应 包 体 


7/ 


}; 


unsigned buffering:1; 


来 缓存 上 游 的 响应 包 体 ， 这 是 有 意义 的 ， 它 可 以 减轻 上 游 服 务 器 的 六 


发 


上 文 介绍 过 ，upstream 有 3 种 处 理 上 游 响 应 包 体 的 方式 ， 但 HTTP 模 
块 如 何 告 诉 upstream 使 用 哪 一 种 方式 处 理 上 游 的 啊 应 包 体 呢 ? 当 请 求 的 
ngx_http_request_t 结 构 体 中 subrequest_in_memory 标 志 位 为 1 时 ， 将 采用 
第 1 种 方式 ， 即 upstream 不 转发 啊 应 包 体 到 下 游 ， 由 HTTP 模 块 实现 的 
input_filter 方 法 处 理 包 体 ， 当 subrequest_in_memory 为 0 上 时，upstream 会 
转发 响应 包 体 。 当 ngx_http_upstream_conf _t 配 置 结构 体 中 的 buffering 标 
志 位 为 1 时 ， 将 开局 更 多 的 内 存 和 磁盘 文件 用 于 缓存 上 六 的 啊 应 包 体 ， 
这 意味 上 游 网 速 更 快 ， 当 buffering 为 0 时 ， 将 使 用 固定 大 小 的 缓冲 区 

(就 是 上 面 介 绍 的 buffer 缓 冲 区 ) 来 转发 响应 包 体 。 


@ 注意 ”上述 的 8 个 回调 方法 中 ， 只 有 create_request 、 
process_header、finalize_request 是 必须 实现 的 ， 其 余 5 个 回调 方法 一 一 
input_ filter_init、input_ filter、reinit _ request、abort request、 
rewrite_redirect 是 可 选 的 。 第 12 章 会 详细 介绍 如 何 使 用 这 5 个 可 选 的 回调 
方法 。 另 外 ， 这 8 个 方法 的 回调 场景 见 5.2m。 


5.1.2 ”设置 upstream 的 限制 性 参数 
本 节 介 绍 的 是 ngx_http_upstream_t 中 的 conf 成 员 ， 它 用 于 设置 
upstream 模 块 处 理 请 求 时 的 参数 ， 包 括 连 接 、 发 送 、 接 收 的 超时 时 间 


和 人 等。 
可 


typedef struct { 


// 连接 上 游 服务 器 的 超时 时 间 ， 单 位 为 毫秒 


ngx_msec_t connect_timeout; 


// 发 送 
TCP 包 到 上 游 服 务 器 的 超时 时 间 ， 单 位 为 毫秒 


ngx_msec_t send_ timeout; 


// 接收 
TCP 包 到 上 游 服 务 器 的 超时 时 间 ， 单 位 为 毫秒 


ngx_msec_t read timeout ， 


} ngx_http_upstream conf_t; 


ngx_http_upstream_conf_t 中 的 参数 有 很 多 ，12.1.3 广 会 完整 地 介绍 
所 有 成 员 。 事 实 上 ，HTTP 反 疝 代理 模块 在 nginx.conf 文 件 中 提供 的 配置 
项 大 都 是 用 来 设置 ngx_http_upstream_conf t 结 构 体 中 的 成 员 的 。 上 面 列 
出 的 3 个 超时 时 间 是 必须 要 设置 的 ， 因 为 它们 默认 为 0， 如 果 不 设置 将 
永远 无 法 与 上 游 服务 器 建立 起 TCP 连 接 (因为 connect_timeout 值 为 
0) 。 


使 用 第 4 章 介 绍 的 14 个 预 设 方法 可 以 非常 答 单 地 通过 nginx.conf 配 置 
文件 设置 ngx_http_upstream_conf t 结 构 体 。 例 如 ， 可 以 把 
ngx_http_upstream_conf_t 类 型 的 变量 放 到 ngx_http_mytest_conf _t 结 构 体 


中 。 


typedef struct { 


ngx_http_upstream conf_t upstream; 
} ngx_http_mytest_conf_t; 


接 下 来 以 设置 connect_timeout 连 接 超时 时 间 为 例 说 明 如 何 编写 
ngx_command t 来 读 取 配 置 文件 。 


static ngx_command_t ngx_http_mytest_commands[] = {... 


{ ngx_string("upstream connect_timeout"), 
NGX_HTTP_LOC_CONF |NGX_CONF_TAKE1., 
ngx_conf_set_msec_slot, 
NGX_HTTP_LOC_CONF_OFFSET, 


/* 给 出 


connect_timeout 成 员 在 


ngx_http_mytest_conf_t 结 构 体 中 的 偏 移 字 节 数 


4 
offsetof(ngx_http_mytest_conf_t, upstream.connect_timeout), 
NULL }, 


这 样 ，nginx.conf 文 件 中 的 upstream_conn_timeout 配 置 项 将 被 解析 
到 ngx_http_mytest_conf_t 结 构 体 的 upstream.connect_timeout 成 员 中 。 在 
处 理 实际 请 求 时 ， 只 要 把 ngx_http_mytest_conf t 配 置 项 的 upstream 成 员 
赋 给 ngx_http_upstream_t 中 的 conf 成 员 即 可 。 例 如 ， 在 
ngx_http_mytest_handler 方 法 中 可 以 这 样 设置 : 
ngx_http mytest conf t *mycf = (ngx_http mytest_ conf t *) 


ngx_http_get module_loc conf(r, ngx_http_mytest_ module); 
r->upstream->conf = &mycf->upstream; 


上 面 代码 中 的 r>upstream->conf 是 必须 要 设置 的 ， 否 则 进程 会 裔 总 
(crash) 。 


注意 ”每 一 个 请 求 都 有 独立 的 ngx_http_upstream_conf {结构 
体 ， 这 意味 着 每 一 个 请 求 都 可 以 拥有 不 同 的 网 络 超时 时 间 等 配置 ， 用 
户 甚至 可 以 根据 HTTP 请 求 信息 决定 连接 上 游 服务 器 的 超时 时 间 、 缓 存 
上 游 响应 包 体 的 临时 文件 存放 位 置 等 ， 这 些 都 只 需要 在 设置 r 
>upstream->conf 时 简单 地 进行 赋值 即 可 ， 有 时 这 非常 有 用 。 


5.1.3 ”设置 需要 访问 的 第 三 方 服务 器 地 址 


ngx_http_upstream_t 结 构 中 的 resolved 成 员 可 以 直接 设置 上 游 服 务 
句 的 地 址 。 肯 先 介 绍 一 下 resolved 的 类 型 。 


typedef struct { 


// 地 址 个 数 


ngx_ naddrs; 


// 下 游 服务 器 的 地 址 


struct sockaddr *sockaddr; 
socklen_t socklen; 


} ngx_http_upstream resolved_t; 


在 ngx_http_upstream_resolved_t 结 构 的 成 员 中 ， 必 须 设置 的 是 上 面 
代码 中 列 出 的 3 个 。 有 具体 设置 的 例子 可 参见 5.3 玉 。 


当然 ， 还 有 其 他 方法 可 以 设置 上 游 服务 器 地 址 ， 感 兴趣 的 读者 可 
以 阅读 upstream 模 块 源 代 码 ， 并 在 nginx.conf 文 件 中 配置 upstream 块 ， 指 
定 上 游 服务 器 的 地 址 。 


5.1.4 设置 回调 方法 


5.1.1 世 介绍 的 ngx_http_upstream_t 结 构 体 中 有 8 个 回调 方法 ， 可 根 
，3 个 必须 实现 的 回调 方法 可 以 这 么 定义 : 


和 
秽 
4 
洁 | 
音 
uly 
;< 
党 
湾 
全 


void mytest_upstream_finalize_request(ngx_http_redquest_t *r, ngx_int_t rc); 
ngx_int_t mytest_upstream create request(ngx_http_request_t *r); 
ngx_int_t mytest_upstream process_ header(ngx_http_request_t *r); 


在 5.3 世 中 ， 会 有 一 个 简单 的 例子 说 明 如 何 实现 上 述 3 个 方法 。 
然后 ， 在 ngx_http_mytest_handler 方 法 中 设置 它们 ， 例 如 : 


r->upstream->create_request = mytest_upstream create request; 
r->upstream->process_header = mytest_process_status_ line,; 
r->upstream->finalize_request=mytest_upstream finalize_request,; 


5.1.5 ”如 何 启动 upstream 机 制 


直接 执行 ngx_http_upstream_init 方 法 即 可 局 动 upstream 机 制 。 例 
如 : 


static ngx_int_t ngx_http_mytest_handler(ngx_http_request_t *r) 


r->main->count++; 
ngx_http_upstream init(r); 
return NGX_DONE ; 

} 


调用 ngx_http_upstream _init 就 是 在 局 动 upstream 机 制 ， 这 时 要 通过 
返回 NGX_DONE 告 诉 HTTP 框 以 暂停 执行 请 求 的 下 一 个 阶段 。 这 里 还 
需要 执行 r>main->count++， 这 是 在 告诉 HTTP 框 架 将 当前 请 求 的 引用 
计数 加 1， 即 告诉 ngx_http_mytest_handler 方 法 暂时 不 要 销毁 请 求 ， 因 为 
HTTP 框 架 只 有 在 引用 计数 为 0 时 才能 真正 地 销毁 请 求 。 这 样 的 话 ， 
upstream 机 制 接 下 来 才能 接管 请 求 的 处 理工 作 。 


@ 注音。 在 阅读 HTTP 反 向 代理 模块 (ngx_http_proxy_module) 
源 代码 时 ， 会 发 现 它 并 没有 调用 r->main->count++， 其 中 proxy 模 块 是 这 
样 启动 upstream 机 制 的 : 
ngx_http_read_client_request_body(r,ngx_http_upstream_init);， 这 表示 读 
取 完 用 户 请 求 的 HTTP 包 体 后 才 会 调用 ngx_http_upstream_init 方 法 启动 
upstream 机 制 (参见 3.6.4 节 ) 。 由 于 ngx_http_read_client_request_body 
的 第 一 行 有 效 语句 是 r->main->count++， 有 所 以 HTTP 反 问 代理 模块 不 能 
再 次 在 其 代码 中 执行 ->main->count++。 


这 个 过 程 看 起 来 似乎 让 人 困惑 。 为 什么 有 时 需要 把 引用 计数 加 1， 
有 时 却 不 需要 呢 ? 因为 ngx_http_read_client_request_body 读 取 请 求 包 体 
是 一 个 异步 操作 (需要 epoll 多 次 调度 才能 完成 的 可 称 其 为 异步 操 
作 ) ，ngx_http_upstream_init 方 法 启用 upstream 机 制 也 是 一 个 异步 操 
作 ， 因 此 ， 从 理论 上 来 说 ， 每 执行 一 次 异步 操作 应 该 把 引用 计数 加 1， 
而 异步 操作 结束 时 应 该 调用 ngx_http_finalize_request 方 法 把 引用 计数 减 
1。 另 外 ，ngx_http_read_client_request_body 方 法 内 是 加 过 引用 计数 的 ， 
而 ngx_http_upstream_init 方 法 内 却 没有 加 过 引用 计数 (或 许 Nginx 将 来 
会 修改 这 个 问题 ) 。 在 HTTP 反 向 代理 模块 中 ， 它 的 
ngx_http_proxy_handler 方 法 中 


用 “ngx_http_read_client_request_body(r,ngx_http_upstream_init);” 语 句 同 
时 启动 了 两 个 异步 操作 ， 注 意 ， 这 行 语句 中 只 加 了 一 次 引用 计数 。 执 
行 这 行 语句 的 ngx_http_proxy_handler 方 法 返回 时 只 调用 

ngx_http_finalize_request 方 法 一 次 ， 这 是 正确 的 。 对 于 mytest 模 块 也 一 


样 ， 务 必要 保证 对 引用 计数 的 增加 和 减少 是 配对 进行 的 。 


5.2 ”回调 方法 的 执行 场景 


使 用 upstream 方 式 时 最 重要 的 工作 都 会 在 回调 方法 中 实现 ， 为 了 更 
好 地 实现 它们 ， 本 市 将 介绍 调用 这 些 回调 方法 的 典型 场景 。 


5.2.1 ”create_request 回 调 方 法 


create_request 的 回调 场景 最 简单 ， 即 它 只 可 能 被 调用 1 次 (如 果 不 
启用 upstream 的 失败 重 试 机 制 的 话 。 详 见 第 12 章 ) ， 如 图 5-3 所 示 。 下 
面 简 单 地 介绍 一 下 图 5-3 中 的 每 一 个 步 又 : 


1) 在 Nginx 主 循环 〈 这 里 的 主 循环 是 指 8.5 节 提 到 的 
ngx_worker_process_cycle 方 法 ) 中 ， 会 定期 地 调用 事件 模块 ， 以 检查 
是 否 有 网 络 事件 发 生 。 


2) 事件 模块 在 接收 到 HTTP 请 求 后 会 调用 HTTP 框 染 来 处 理 。 假 设 
接收 、 解 析 完 HITP 头 部 后 发 现 应 该 由 mytest 模 块 处理 ， 这 时 会 调用 
mytest 模 块 的 ngx_http_mytest_handler 来 处 理 。 


3) 这 里 mytest 模 块 此 时 会 完成 5.1.2 节 ~5.1.4 节 中 所 列 出 的 步骤 。 


4) 调用 ngx_http_upstream_init 方 法 局 动 upstream 。 


| | | | 
| | | | 


| 


2. 经 过 HTTP 核心 模块 调用 mytest 模块 
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| 
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| 
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6. 调 create _reduest 
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图 5-3 ”create_request 回 调 场 景 的 序列 图 


5) upstream 模 块 会 去 检查 文件 缓存 ， 如 果 缓 存 中 已 经 有 合适 的 响 
应 包 ， 则 会 直接 返回 缓存 (当然 必须 是 在 使 用 反 向 代理 文件 缓存 的 前 
提 下 ) 。 为 了 让 读者 方便 地 理解 upstream 机 制 ， 本 章 将 不 再 提 及 文件 组 
存 。 


6) 回调 mytest 模 块 已 经 实现 的 create_request 回 调 方 法 。 


7) mytest 模 块 通过 设置 r>upstream->request_bufs 已 经 决定 好 发 送 
什么 样 的 请 求 到 上 游 服务 器 。 


8) upstream 模 块 将 会 检查 5.1.3 广 中 介绍 过 的 resolved 成 员 ， 如 果 有 
resolved 成 员 的 话 ， 束 根据 它 设置 好 上 游 服 务 絮 的 地 址 r->upstream->peer 


11) ngx_http_upstream_init 返 回 。 
12) mytest 模 块 的 ngx_http_mytest_handler 方 法 返回 NGX_DONE 。 


13) 当 事 件 模块 处 理 完 这 批 网 络 事件 后 ， 将 控制 权 交 还 给 Nginx 主 
循环 。 


5.2.2 ”reinit_request 回 调 方 法 


reinit request 可 能 会 被 多 次 回调 。 它 家 调用 的 原因 只 有 一 个 ， 束 是 
在 第 一 次 试图 向 上 游 服 务 器 建立 连接 时 ， 如 果 连 接 由 于 各 种 异常 原因 


失败 ， 那 么 会 根据 upstream 中 conf 参 数 的 策略 要 求 再 次 重 连 上 游 服 务 
器 ， 而 这 时 就 会 调用 reinit_request 方 法 了 。 图 5-4 摘 述 了 典型 的 


reinit_request 调 用 场景 。 
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| 
9.Nginx 与 第 三 方 服务 连接 断 开 
10. 再 次 建立 TCP 连 接 


11. 无 阻塞 地 建立 连接 调用 返回 
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12 .检查 request_sent 时 发 现 已 经 为 ] 
13. 回调 reinit _ request 


14. 回调 方法 执行 完毕 
> 


15.TCP 连接 断 开 事件 处 理 完毕 


16 处 理 完 毕 


图 5-4 reinit_ request 回调 场景 的 序列 图 


下 面 简单 地 介绍 一 下 图 5-4 中 列 出 的 步骤。 


1) Nginx 主 循环 中 会 定期 地 调用 事件 模块 ， 检 查 是 否 有 网 络 事 件 
发 生 。 


2) 事件 模块 在 确定 与 上 游 服 务 器 的 TCP 连 接 建立 成 功 后 ， 会 回调 
upstream 模 块 的 相关 方法 处 理 。 


3) upstream 模 块 这 时 会 把 ~>upstream->request_sent 标 志 位 置 为 1， 
表示 连接 已 经 建立 成 功 了 ， 现 在 开始 向 上 游 服 务 器 发 送 请 求 内 容 。 


4) 发 送 请 求 到 上 游 服 务 器 。 


5) 发 送 方法 当然 是 无 阻塞 的 (使 用 了 无 阻塞 的 套 接 字 ) ， 会 立刻 
返回 。 


6) upstream 模 块 处 理 第 2 步 中 的 TCP 连 接 建立 成 功 事件 。 


7) 事件 模块 处 理 完 本 轮 网 络 事件 后 ， 将 控制 权 交 还 给 Nginx 主 循 
环 。 


8) Nginx 主 循环 重复 第 1 步 ， 调 用 事件 模块 检查 网 络 事件 。 


9) 这 时 ， 如 果 发 现 与 上 游 服务 器 建立 的 TCP 连 接 已 经 异常 断 开 ， 
那么 事件 模块 会 通知 upstream 模 块 处 理 它 。 


10) 在 符合 重 试 次 数 的 前 提 下 ，upstream 模 块 会 毫 不 犹豫 地 再 次 用 
无 阻塞 的 套 接 字 试 图 建立 连接 。 


11) 无 论 连 接 是 否 建立 成 功 都 立刻 返回 。 


12) 这 时 检查 r->upstream->request_sent 标 志 位 ， 会 发 现 它 已 经 被 置 


J 


13) 如 果 mytest 模 块 没 有 实现 reinit_request 方 法， 那么 是 不 会 调用 
它 的 。 而 如 果 reinit_request 不 为 NULL 空 指针 ， 就 会 回调 它 。 


14) mytest 模 块 在 reinit request 中 处 理 完 目 己 的 事情 。 


15) 处 理 完 第 9 步 中 的 TCP 连 接 断 开 事件 ， 将 控制 权 交 还 给 事件 模 
块 。 


16) 事件 模块 处 理 完 本 轮 网 络 事件 后 ， 交 还 控制 权 给 Nginx 主 循 
环 。 


5.2.3 ”finalize_request 回 调 方法 


当 调 用 ngx_http_upstream_init 启 动 upstream 机 制 后 ， 在 各 种 原 
(无 论 成 功 还 是 失败 ) 导致 该 请 求 被 销毁 前 都 会 调用 finalize_request 方 
法 〈 参 见 图 5-1) 


在 finalize_request 方 法 中 可 以 不 做 任何 事情 ， 但 必须 实现 
finalize_request 方 法 ， 否 则 Nginx 会 出 现 空 指针 调用 的 严重 错误 。 


5.2.4 ”process_header 回 调 方 法 


process_header 是 用 于 解析 上 游 服 务 絮 返回 的 基于 TCP 的 啊 应 头 部 
的 ， 因 此 ，process_header 可 能 会 被 多 次 调用 ， 它 的 调用 次 数 与 
process_header 的 返回 值 有 关 。 如 图 5-5 所 示 ， 如 有 果 process_header 返 回 
NGX_AGAIN， 这 意味 着 还 没有 接收 到 完整 的 啊 应 头 部 ， 如 有 果 再 次 接 
收 到 上 游 服务 句 发 来 的 TCP 流 ， 还 会 把 它 当 做 头 部 ， 仍 然 调 用 
process_header 处 理 。 而 在 图 5-6 中 ， 如 采 process_header 返 回 NGX_OK 
(或 者 其 他 非 NGX_AGAIN 的 值 ) ， 那 么 在 这 次 连接 的 后 续 处 理 中 将 
不 会 再 次 调用 process_header 。 
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5. 调用 process _header 方 法 解析 包头 


[一 一 到 --------------[--- 


6 回调 方法 执行 完毕 
一 


We process_header 返回 NGX_AGAIN 


1 
| 
| 
8. 再 次 读 取 套 接 字 | 


图 5-5 “process_header 回 调 场景 的 序列 图 


下 面 简单 地 介绍 一 下 图 5-5 中 列 出 的 步骤 。 


1) Nginx 主 循环 中 会 定期 地 调用 事件 模块 ， 检 查 是 否 有 网 络 事件 
发 全 


2) 事件 模块 接收 到 上 游 服务 器 发 来 的 啊 应 时 ， 会 回调 upstream 模 
块 处 理 。 


3) upstream 模 块 这 时 可 以 从 套 接 字 缓冲 区 中 读 取 到 来 自 上 游 的 
TCP 流 。 


4) 读 取 的 响应 会 存放 到 r>upstream->buffer 指 向 的 内 存 中 。 注 意 : 

在 未 解析 完 响应 头 部 前 ， 若 多 次 接收 到 字符 流 ， 所 有 接收 自 上 游 的 响 

应 都 会 完整 地 存放 到 r->upstream->buffer 缓 冲 区 中 。 因 此 ， 在 解析 上 游 
响应 包头 时 ， 如 果 buffer 缓 冲 区 全 满 却 还 没有 解析 到 完整 的 响应 头 部 

(也 就 是 说 ，process_header 一 直 在 返回 NGX_AGAIN) ， 那 么 请 求 就 


会 恒信 


5) 调用 mytest 模 块 实现 的 process_header 方 法 。 


6) process_header 方 法 实际 上 就 是 在 解析 r->upstream->buffer 缓 冲 
区 ， 试 图 从 中 取 到 完整 的 响应 头 部 (当然 ， 如 果 上 游 服 务 器 与 Nginx 通 
过 HTTP 通 信 ， 就 是 接收 到 完整 的 HTTP 头 部 ) 。 


7) 如 果 process_header 返 回 NGX_AGAIN， 那 么 表示 还 没有 解析 到 
完整 的 啊 应 头 部 ， 下 次 还 会 调用 process_header 处 理 接收 到 的 上 游 啊 


Yo 


8) 调用 无 阻塞 的 读 取 套 接 字 接口 。 


9) 这 时 有 可 能 返回 套 接 字 缓冲 区 已 经 为 空 。 


10) 当 第 2 步 中 的 读 取 上 游 啊 应 事件 处 理 完毕 后 ， 控 制 权 交还 给 事 
件 模块 。 


11) 事件 模块 处 理 完 本 轮 网 络 事件 后 ， 交 还 控制 权 给 Nginx 主 循 
环 。 


5.2.5 ”rewrite_redirect 回 调 方法 


在 重 定 辣 URL 阶 段 ， 如 采 实 现 了 rewrite_redirect 回 调 方 法 ， 那 么 这 
时 会 调用 rewrite_redirect。 注 意 ， 本 章 不 涉及 rewrite_redirect 方 法 ， 感 兴 
趣 的 读者 可 以 查看 upstream 模 块 的 ngx_http_upstream_rewrite_location 方 
法 。 如 果 upstream 模 块 接收 到 完整 的 上 游 啊 应 头 部 ， 而 且 由 HTTP 模 块 
的 process_header 回 调 方法 将 解析 出 的 对 应 于 Location 的 头 部 设置 到 了 
ngx_http_upstream_t 中 的 headers_in 成 员 时 ， 
ngx_http_upstream_process_headers 方 法 将 会 最 终 调 用 rewrite_redirect 方 
法 ( 见 12.5.3 节 图 12-5 的 第 8 步 ) 。 因 此 ，rewrite_redirect 的 使 用 场景 比 
较 少 ， 它 主要 应 用 于 HTTP 肥 问 代 理 模 块 (ngx_http_proxy_module) 。 


5.2.6 ”input_filter_init 与 input_filter 回 调 方 法 


input_filter_init 与 input_filter 这 两 个 方法 都 用 于 处 理 上 游 的 啊 应 包 
体 ， 因 为 处 理 包 体 前 HTTP 模 块 可 能 需要 做 一 些 初始 化 工作 。 例 如 ， 分 
配 一 些 内 存 用 于 存放 解析 的 中 间 状 态 等 ， 这 时 upstream 束 提供 了 
input_filter_init 方 法 。 而 ipput_filter 方 法 束 是 实际 处 理 包 体 的 方法 。 这 两 
个 回调 方法 都 可 以 选择 不 予 实现 ， 这 是 因为 当 这 两 个 方法 不 实现 时 ， 
upstream 模 块 会 自动 设置 它们 为 预 置 方 法 (上 文 讲 过 ， 由 于 upstream 有 3 
种 处 理 包 体 的 方式 ， 所 以 upstream 模 块 准备 了 3 对 input_filter_init 、 
input_filter 方 法 ) 。 因 此 ， 一 旦 试图 重 定义 input_filter_init 、input_filter 
方法 ， 就 意味 着 我 们 对 upstream 模 块 的 默认 实现 是 不 满意 的 ， 所 以 才 要 
重 定义 该 功能 。 此 时 ， 百 移 必 须要 弄 请 私 默 认 的 input_filter 方 法 到 撒 做 
了 什么 ， 在 12.6 节 ~12.8 世 介绍 的 3 种 处 理 包 体 方式 中 ， 都 会 涉及 默认 的 
input_filter 方 法 所 做 的 工作 。 


在 多 数 情况 下 ， 会 在 以 下 场景 决定 重新 实现 input_filter 方 法 。 
(1) 在 转发 上 游 响 应 到 下 游 的 同时 ， 需 要 做 一 些 特殊 处 理 


例如 ，ngx_http_memcached_module 模 块 会 将 实际 由 memcached 实 
现 的 上 游 服 务 硕 返回 的 啊 应 包 体 ， 转 发 到 下 游 的 HTTP 客 户 疹 上 。 在 上 
述 过 程 中 ， 该 模块 通过 重 定义 了 的 input_filter 方 法 来 检测 memcached 协 
议 下 包 体 的 结束 ， 而 不 是 完全 、 纯 粹 地 透 传 TCP 流 。 


(2) 当 无 须 在 上 、 下 游 间 转发 响应 时 ， 并 不 想 等 待 接 收 完全 部 的 
上 上 游 啊 应 后 才 开 始 处 理 请 求 


在 不 转发 啊 应 时 ， 通 常会 将 响应 包 体 存放 在 内 存 中 解析 ， 如 果 试 
图 接收 到 完整 的 啊 应 后 再 来 解析 ， 由 于 响应 可 能 会 非常 大 ， 这 会 占用 
大 量 内 存 。 而 重 定 义 了 input_filter 方 法 后 ， 可 以 每 解析 完 一 部 分 包 体 ， 
束 释 放 一 些 内 存 。 


重 定 义 input_filter 方 法 必须 符合 一 些 规 则 ， 如 怎样 取 到 刚 接收 到 的 
包 体 以 及 如 何 释放 缓冲 区 使 得 固定 大 小 的 内 存 缓冲 区 可 以 重复 使 用 
等 。 注 意 ， 本 章 的 例子 并 不 涉及 input_filter 方 法 ， 读 者 可 以 在 第 12 章 中 
找到 input_filter 方 法 的 使 用 方式 。 


5.3 ”使 用 upstream 的 示例 


下 面 以 一 个 简单 且 能 够 运行 的 示例 帮助 读者 理解 如 何 使 用 
upstream 机 制 。 这 个 示例 要 实现 的 功能 很 简单 ， 即 以 访问 mytest 模 块 的 
URL 参 数 作为 搜索 引擎 的 关键 子 ， 用 upstream 方 式 访问 google， 查 询 
URL 里 的 参数 ， 然 后 把 google 的 结果 返回 给 用 户 。 这 个 场景 非常 适合 
使 用 upstream 方 式 ， 因 为 Nginx 访 问 google 的 服务 器 使 用 的 是 HITP， 它 
当然 符合 upstream 的 使 用 场景 ， 上 游 服 务 器 提供 基于 TCP 的 协议 。 上 文 
讲 过 ，upstream 提 供 了 3 种 处 理 包 体 的 方式 ， 这 里 选择 以 固定 缓冲 区 癌 
下 游客 户 端 转发 google 返 回 的 包 体 (HTTP 的 包 体 ) 的 方式 。 


例如 ， 如 果 访 问 的 URL 是 /test?lumia， 那 么 在 nginx.conf 中 可 以 这 
样 配 置 location 。 


location /test { 
mytest; 


mytest 模 块 将 会 使 用 upstream 机 制品 www.google.com 发 送 搜索 请 
求 ， 它 的 请 求 UREL 是 /search?q=lumia，google 返 回 的 包头 将 在 mytest 模 
块 中 解析 并 决定 如 何 转发 给 用 户 ， 而 包 体 将 会 被 透 传 给 用 户 。 


里 继续 以 mytest 模 块 为 例 来 说 明 如 何 使 用 upstream 达 成 上 述 效 
果 o 


5.3.1 upstream 的 各 种 配置 参数 


每 一 个 HITP 请 求 都 会 有 独立 的 ngx_http_upstream_conf_t 结 构 体 ， 
出 于 简单 考虑 ， 在 mytest 模 块 的 例子 中 ， 所 有 的 请 求 都 将 共享 同一 个 
ngx_http_upstream_conf t 结 构 体 ， 因 此 ， 这 里 把 它 放 到 
ngx_http_mytest_conf_t 配 置 结构 体 中 ， 如 下 所 示 。 


typedef struct { 
ngx_http_upstream conf_t upstream; 
} ngx_http_mytest_conf_t; 


在 启动 upstream 前 ， 先 将 ngx_http_mytest_conf_t 下 的 upstream 成 员 
赋 给 r->upstream->conf 成 员 ， 可 参考 5.3.6 市 中 的 示例 代码 。 


ngx_http_upstream_conf t 结 构 中 的 各 成 员 可 以 通过 第 4 草 中 介绍 的 
方法 ， 即 用 预 设 的 配置 项 解析 参数 来 赋值 ， 如 5.1.2 节 中 的 例子 所 示 。 
出 于 方便 ， 这 里 直接 硬 编码 到 create_loc_conf 回 调 方法 中 了 ， 如 下 所 


修 ° 


static void* ngx_http_mytest_ create loc conf(ngx_conf_t *cf) 


ngx_http_mytest_conf 七 *mycf， 
mycf = (ngx_http_mytest_conf t *)ngx_pcalloc(cf->pool, 
sizeof(ngx_http_mytest_conf_t)); 
if (mycf == NULL) { 
return NULL; 


} 
/* 以 下 简单 的 硬 编码 


ngx_http_upstream_conf_t 结 构 中 的 各 成 员 ， 如 超时 时 间 ， 都 设 为 


1 分 钟 ， 这 也 是 


HTTP 反 向 代理 模块 的 默认 值 


4 
mycf->upstream.connect_timeout = 60000; 
mycf->upstream.send_timeout = 60000; 
mycf->upstream.read_timeout = 60000; 
mycf->upstream.store_access = 0600; 
/* 实 际 上 ， 
buffering 已 经 决定 了 将 以 固定 大 小 的 内 存 作 为 缓冲 区 来 转发 上 游 的 响应 包 体 ， 这 块 固定 缓冲 区 的 大 小 就 是 


buffer_size。 如 果 
buffering 为 
1， 就 会 使 用 更 多 的 内 存 缓存 来 不 及 发 往 下 游 的 响应 。 例 如 ， 最 多 使 


HH 


bufs .num 个 缓冲 区 且 每 个 缓冲 区 大 小 为 


各 时 文件 ， 临 时 文件 的 最 大 长 度 为 


二 


bufs .Size。 另 外 ， 还 会 使 用 | 


max_temp_file size*/ 
mycf->upstream,buffering = 0; 
mycf->upstream,bufs,num = 8; 
mycf->upstream,bufs.Size = ngx_pagesize,; 
mycf->upstream,buffer_size = ngx_pagesize,; 
mycf->upstream.busy_buffers_size = 2*ngx_pagesize; 
mycf->upstream.temp_file write size = 2 * ngx_pagesize; 
mycf->upstream.max_temp_file_ size = 1024 * 1024 * 1024; 
/*upstream 模 块 要 求 


hide_headers 成 员 必 须要 初始 化 ( 


upstream 在 解析 完 上 游 服务 器 返回 的 包头 时 ， 会 调用 


| 


ngx_http_upstream_process_headers 方 法 按照 


hide_headers 成 员 将 本 应 转发 给 下 游 的 一 些 


HTTP 头 部 隐藏 ) ， 这 里 将 它 赋 为 


NGX_CONF_UNSET_PTR ， 这 是 为 了 在 


merge 合 并 配置 项 方法 中 使 用 


upstream 模 块 提 供 的 


ngx_http_upstream_hide_headers_hash 方 法 初始 化 
hide_headers 成 员 
4 


mycf->upstream.hide_ headers 
mycf->upstream.pass_headers 


NGX_CONF_UNSET_PTR， 
NGX_CONF_UNSET_PTR， 


ll 


return mycf， 


} 


hide_headers 的 类 型 是 ngx_array_t 动 态 数组 (实际 上 ，upstream 模 
块 将 会 通过 hide_headers 来 构造 hide_headers_hash 散 列表 ) 。 由 于 
upstream 模 块 要 求 hide_headers 不 可 以 为 NULL， 所 以 必须 要 初始 化 
hide_headers 成 员 。upstream 模 块 提供 了 
ngx_http_upstream_hide_headers_hash 方 法 来 初始 化 hide_headers， 但 仪 
可 用 在 合并 配置 项 方法 内 。 例 如 ， 在 下 面 的 
ngx_http_mytest_merge_loc_conf 方 法 中 束 可 以 使 用 ， 如 下 所 示 ， 


static char *ngx_http_mytest _ merge loc conf(ngx_conf_t *cf, void *parent, void 
*child) 
{ 


ngx_http_mytest_conf t *prev = (ngx_http_mytest conf_t *)parent,; 
ngx_http_mytest_conf t *conf = (ngx_http_mytest_conf t *)child; 
ngx_hash_init_t hash,; 
hash.max_size = 100; 
hash.bucket_size = 1024; 
hash.name = "proxy_headers_hash",， 
If (ngx_http_upstream hide headers hash(cf, &conf->upstream, 
&prev->upstream, ngx_http_proxy_hide headers, &hash) 
!= NGX_OK) 


return NGX_CONF_ERROR, 


return NGX_CONF_OK; 


53.2 请 求 上 下 工 


本 市 介绍 的 例子 束 必 须要 使 用 上 下 文才 能 正确 地 解析 upstream 上 
游 服务 器 的 啊 应 包 ， 因 为 upstream 模 块 每 次 接收 到 一 段 TCP 流 时 都 会 回 
调 mytest 模 块 实现 的 process_header 方 法 解析 ， 这 样 就 需要 有 一 个 上 下 


文保 存 解析 状态 。 在 解析 HTTP 啊 应 行 时 ， 可 以 使 用 HTTP 框 架 提供 的 
ngx_http_status_t 结 构 ， 如 下 所 示 。 


typedef struct { 


ngx_uint_t code; 
ngx_uint_t count; 
u_char *start,; 
u_char *end; 


} ngx_http_status_t; 


把 ngx_http_status_t 结 构 放 到 上 下 文中 ， 并 在 process_header 解 析 咯 
应 行 时 使 用 ， 如 下 所 示 。 


typedef struct { 
ngx_http_status_t status,; 
} ngx_http_mytest ctx_t; 


在 5.3.4 节 实现 process_header 的 代码 中 ， 可 以 学 会 如 何 使 用 


ngx_http_status_t 结 构 。 
5.3.3 ”在 create_request 方 法 中 构造 请 求 


这 里 定义 的 mytest_upstream_create_request 方 法 用 于 创建 发 送 给 上 
条 
务 


游 服务 器 的 HTTP 请 求 ，upstream 模 块 将 会 回调 它 ， 实 现 如 下 。 


static ngx_int_t 
mytest_upstream create_request(ngx_http_request_t *r) 


/* 发 往 


go0gle 上 游 服务 器 的 请 求 很 简单 ， 就 是 模仿 正常 的 搜索 请 求 ， 以 


/searchq=... 的 


URL 来 发 起 搜索 请 求 。 


backendQueryLine 中 的 


%V 等 转化 格式 的 用 法 ， 可 参见 表 


4-7*/ 
static ngx_str_t backendQueryLine = 
ngx_string("GET /searchq=%V HTTP/1.1\r\nHost: 
www.google.com\r\nConnection: close\r\n\r\n"); 
ngx_int_t queryLineLen = backendQueryLine.len + r->args.len - 2; 


/* 必 须 在 内 存 池 中 申请 内 存 ， 这 有 以 下 两 点 好 处 : 一 个 好 处 是 ， 在 网 络 情况 不 佳 的 情况 下 ， 向 上 游 服 务 器 
发 送 请 求 时 ， 可 能 需要 
epo11 多 次 调度 


send 才 能 发 送 完成 ， 这 时 必须 保证 这 段 内 存 不 会 被 释放 ; 另 一 个 好 处 是 ， 在 请 求 结束 时 ， 这 段 内 存 会 被 自动 释 
放 ， 降 低 内 存 泄 漏 的 可 能 


*/ 
ngx_buf_t* b = ngx_create temp_buf(r->pool, queryLineLen); 
if (b == NULL) 
return NGX_ERROR; 
// 1ast 要 指向 请 求 的 末尾 


tt 


b->last = b->pos + queryLineLen, 


// 作用 相当 了 


i 


snprintf， 只 是 它 支 持 表 


4-7 中 列 出 的 所 有 转换 格式 


ngx_snprintf(b->pos, queryLineLen ， 
(char*)backendQueryLine.data, &r->args); 
/* r->upstream->request_bufs 是 一 个 


ngx_chain_t 结 构 ， 它 包含 着 要 发 送 给 上 游 服 务 器 的 请 求 


*/ 
r->upstream->request_bufs = ngx_alloc_ chain_ link(r->pool); 
if (r->upstream->request_bufs == NULL) 
return NGX_ERROR; 
// request_bufs 在 这 里 只 包含 


1 


[XI 


ngx_buf_t 缓 冲 


r->upstream->request_bufs->buf = b; 
r->upstream->request_bufs->next = NULL; 
r->upstream->request_sent = 0; 
r->upstream->header_sent = 0; 

// ”header_hash 不 可 以 为 


r->header_hash = 1; 
return NGX_OK， 


5.3.4 在 process_header 方 法 中 解析 包头 


process_header 负 责 解析 上 游 服务 器 发 来 的 基于 TCP 的 包头 ， 在 本 
例 中 ， 就 是 解析 HTTP 响 应 行 和 HTTP 头 部 ， 因 此 ， 这 里 使 用 
mytest_process_status_jline 方 法 解析 HTTP 响 应 行 ， 使 用 
mytest_Upstream_process_header 方 法 解析 http 咱 应 头 部 。 之 所 以 使 用 两 
个 方法 解析 包头 ， 这 也 是 HTTP 的 复杂 性 造成 的 ， 因 为 无 论 是 响应 行 还 
是 响应 头 部 都 是 不 定 长 的 ， 都 需要 使 用 状态 机 来 解析 。 实 际 上 ， 这 两 
个 方法 也 是 通用 的 ， 它 们 适用 于 解析 所 有 的 HITP 响 应 包 ， 而 且 这 两 个 
方法 的 代码 与 ngx_http_proxy_module 模 块 的 实现 几乎 是 完全 一 致 的 。 


static ngx_int_t 
mytest_process_status_line(ngx_http_request_t *r) 


size_t len; 
ngx_int_t re; 
ngx_http_upstream t *U; 
// 上 下 文中 才 会 保存 多 次 解析 


HTTP 响 应 行 的 状态 ， 下 面 首先 取出 请 求 的 上 下 文 


ngx_http_mytest_ctx_t* ctx = 
ngx_http_get_ module ctx(r,ngx_http_mytest module); 
If (ctx == NULL) { 
return NGX_ERROR ， 
} 


U = r->upstream,; 
/*HTTP 框 架 提供 的 


ngx_http_parse_status_line 方 法 可 以 解析 


HTTP 响 应 行 ， 它 的 输入 就 是 收 到 的 字符 流 和 上 下 文中 的 


ngx_http_status_t 结 构 


*/ 
rc = ngx_http_parse_status_ line(r, &u->buffer, &ctx->status); 
// 返 匠 


NGX_AGAIN 时 ， 表 示 还 没有 解析 出 完整 的 


ba 


HTTP 响 应 行 ， 需 要 接收 更 多 的 字符 流 再 进行 解析 


*/ 
if (rc == NGX_AGAIN) { 
return rc; 
} 


// 返 匠 


NGX_ERROR 时 ， 表 示 没 有 接收 到 合法 的 


HTTP 响 应 行 


if (rc == NGX_ERROR) { 
ngx_log_error(NGX_LOG_ERR, r->connection->log, 909, 
"upstream sent no Valid HTTP/1.0 header"); 
r->http_version = NGX_HTTP_VERSION_ 9; 
U->State->Sstatus = NGX_HTTP_OK,; 
return NGX_OK; 


} 
/* 以 下 表示 在 解析 到 完整 的 
会 做 一 些 简单 的 赋值 操作 ， 将 解析 出 的 信息 设置 到 


HTTP 响 应 行 时 


a 


r->upstream->headers_in 结 构 体 中 。 


upstream 解 析 完 所 有 的 包头 时 ， 会 把 
headers_in 中 的 成 员 设 置 到 将 要 向 下 游 发 送 的 


r->headers_out 结 构 体 中 ， 也 就 是 说 ， 现 在 用 户 向 


headers_in 中 设置 的 信息 ， 最 终 都 会 发 往 下 游客 户 端 。 为 什么 不 直接 设 


r->headers_out 而 要 多 此 一 举 呢 ? 因为 


upstream 和 希望 能 够 按照 


ngx_http_upstream_conf_t 配 置 结构 体 中 的 


t 


hide_headers 等 成 员 对 发 往 下 游 的 响应 头 部 做 统一 处 理 


*/ 
if (u->state) { 
Uu->state->status = ctx->status,.code; 


uU->headers_in.status_n = ctx->status.code; 
len = ctx->status.end - ctx->status.start,; 
uU->headers_in.status_line.]len = len; 
u->headers_in.status_line.data = ngx_pnalloc(r->pool, len); 
If (u->headers_in.status_ line.data == NULL) { 

return NGX_ERROR ， 
} 


ngx_memcpy(u->headers_in,.status_ line.data, ctx->status.start, 
/* 下 一 步 将 开始 解析 


HTTP 头 部 。 设 


len); 


process_header 回 调 方法 为 


mytest_upstream_process_header， 之 后 再 收 到 的 新 字符 流 将 


mytest_upstream_process_header 解 析 

6 
U->process_header = mytest_upstream process_header; 
/* 如 果 本 次 收 到 的 字符 流 除了 


HTTP 响 应 行 外 ， 还 有 多 余 的 字符 ， 那 么 将 


mytest_upstream_process_header 方 法 解析 
A 


} 


return mytest_upstream process_header(r); 


mytest_upstream_process_header 方 法 可 以 解析 HTTP 啊 应 头 部 ， 而 
这 个 例子 只 是 简单 地 把 上 游 服务 絮 发 送 的 HTTP 尖 部 添加 到 了 请 求 r- 
>upstream->headers_in.headers 链 表 中 。 如 果 有 需要 特殊 处 理 的 HITTP 头 
部 ， 那 么 也 应 该 在 mytest_upstream_process_header 方 法 中 进行 。 


static ngx_int_t 
mytest_upstream process_header(ngx_http_request_t *r) 


{ 
ngx_int_t FC 
ngx_table elt_t *h; 
ngx_http_upstream_header_t *hh ， 
ngx_http_upstream_main_conf t *umcf; 
/* 这 里 将 

upstream 模 块 配置 项 


ngx_http_upstream_main_conf_t 取 出 来 ， 目 的 只 有 一 个 ， 就 是 对 将 要 转发 给 下 游客 户 端的 
HTTP 响 应 头 部 进行 统一 处 理 。 该 结构 体 中 存储 了 需要 进行 统一 处 理 的 
HTTP 头 部 名 称 和 回调 方法 


*/ 
umcf = ngx_http_get module main_ conf(r, ngx_http_upstream module); 
// 循环 地 解析 所 有 的 

HTTP 头 部 


for ( ;; ) 攻 
/* HTTP 框 架 提供 了 基础 性 的 


ngx_http_parse_header_line 方 法 ， 它 用 于 解析 


HTTP 头 部 


*/ 


ngx_http_parse_ header_line(r, &r->upstream->buffer, 1); 
口 


NGX_0OK 时 ， 表 示 解 析出 一 行 
HTTP 头 部 
if (rc == NGX_OK) { 
// 向 


headers_in.headers 这 个 


ngx_list_t 链 表 中 添加 


HTTP 头 部 
h = ngx_list_push(&r->upstream->headers_in.headers); 
if (h == NULL) { 
return NGX_ERROR ， 
} 
// 下 面 开 始 构 造 刚刚 添加 到 
headers 链 表 中 的 
HTTP 头 部 


h->hash = r->header_hash 
h->key.len = r->header_name_end - r->header name_start,; 
h->value.len = r->header_end - r->header_start; 


// 必须 在 内 存 池 中 分 配 存放 
HTTP 头 部 的 内 存 空 间 


h->key.data = ngx_pnalloc(r->pool, 
h->key.len + 1 + h->value.len + 1 + h->key.1en); 
If (h->key.data == NULL) { 
return NGX_ERROR ， 
} 


h->value.data = h->key.data + h->key.len + 1; 

h->lowcase_key = h->key.data + h->key.len + 1 + h->value.len + 1; 
ngx_memcpy(h->key.data, r->header_name_start, h->key.1en); 
h->key.data[h->key.len] = '\0'，; 

ngx_memcpy(h->value.data, r->header_start, h->value.1len); 


h->value.data[h->value.len] = '\0'， 

if (h->key.len == r->lowcase_ index) { 
ngx_memcpy(h->lowcase_key, r->lowcase_header, h->key.1en); 

} else { 


ngx_strlow(h->lowcase_key, h->key.data, h->key.1en); 


} 
// upstream 模 块 会 对 一 些 


HTTP 头 部 做 特殊 处 理 


hh = ngx_hash_find(&umcf->headers_in_hash，h->hash， 


h->lowcase_key, h->key.1len); 
If (hh && hh->handler(r, h, hh->offset) != NGX _ OK) { 


return NGX_ERROR; 
} 


continue; 


} 
/* 返 回 


NGX_HTTP_PARSE_HEADER_DONE 时 ， 表 示 响 应 中 所 有 的 


HTTP 头 部 都 解析 完毕 ， 接 下 来 再 接收 到 的 都 将 是 
HTTP 包 体 


ph 
if (rc == NGX_HTTP_PARSE_HEADER_ DONE) { 
/* 如 果 之 前 解析 


HTTP 头 部 时 没有 发 现 


server 和 


date 头 部 ， 那 么 下 面 会 根据 


HTTP 协 议 规范 添加 这 两 个 头 部 


*/ 
If (r->upstream->headers_in.server == NULL) { 


h = ngx_list_push(&r->upstream->headers_in.headers); 


if (h == NULL) { 
return NGX_ERROR; 
} 


h->hash = ngx_hash(ngx_hash(ngx_hash(ngx_hash( 
ngx_hash('s', 'e'), ‘'r'), 


ngx_str_set(&h->key, "Server"); 
ngx_str_null(&h->value); 
h->lowcase_key = (u_char *) "server",; 


} 
if (r->upstream->headers_in.date == NULL) { 
h = ngx_list_push(&r->upstream->headers_in.headers); 
if (h == NULL) { 
return NGX_ERROR ， 
} 
h->hash = ngx_hash(ngx_hash(ngx_hash('d', 'a'), 't'), 
ngx_str_set(&h->key, "Date"); 
ngx_str_null(&h->value); 
h->lowcase_key = (u_char *) "date"; 
} 


return NGX_OK; 


} 
/* 如 果 返 回 


NGX_AGAIN， 则 表示 状态 机 还 没有 解析 到 完整 的 


HTTP 头 部 ， 此 时 要 求 


upstream 模 块 继 续 接 收 新 的 字符 流 ， 然 后 交 由 


调 方法 解析 


五 


process_header 


if (rc == NGX_AGAIN) { 
return NGX_AGAIN 
} 


// 其 他 返回 值 都 是 非法 的 


ngx_log_error(NGX_LOG_ERR, r->connection->log, 0, 
"upstream sent invalid header"); 
return NGX_HTTP_UPSTREAM_INVALID_HEADER ， 


当 mytest_upstream_process_header 返 回 NGX_OK 后 ，upstream 模 块 
开始 把 上 游 的 包 体 (如 果 有 的 话 ) 直接 转发 到 下 游客 户 端 。 


5.3.5 ”在 finalize_request 方 法 中 释放 资源 


当 请 求 结束 时 ， 将 会 回调 finalize_request 方 法 ， 如 果 我 们 希望 此 时 
释放 资源 ， 如 打开 的 句柄 等 ， 那 么 可 以 把 这 样 的 代码 添加 到 
finalize_request 方 法 中 。 本 例 中 定义 了 mytest_upstream_finalize_request 
方法 ， 由 于 我 们 没有 任何 需要 释放 的 资源 ， 所 以 该 方法 没有 完成 任何 
实际 工作 ， 只 是 因为 upstream 模 块 要 求 必 须 实 现 finalize request 回调 方 
法 ， 如 下 所 示 。 


static void 
mytest_upstream finalize_request(ngx_http_request_t *r, ngx_int_t rc) 


ngx_log_error(NGX_LOG_ DEBUG, r->connection->1o0g,0, 
"mytest_upstream finalize_request"); 


5.3.6 ”在 ngx_http_mytest_handler 方 法 中 启动 upstream 


在 开始 介入 处 理 客户 端 请 求 的 ngx_http_mytest_handler 方 法 中 启动 
upstream 机 制 ， 而 何 时 请 求 会 结束 ， 则 视 Nginx 与 上 游 的 google 服 务 器 
间 的 通信 而 定 。 通 常 ， 在 启动 upstream 时 ， 我 们 将 决定 以 何 种 方式 处 
理 上 游 响 应 的 包 体 ， 前 文 说 过 ， 我 们 会 原封 不 动 地 转发 google 的 响应 
包 体 到 客户 端 ， 这 一 行为 是 由 ngx_http_request_t 结 构 体 中 的 
subrequest_in_memory 标 志 位 决定 的 ， 默 认 情 况 下 ， 
subrequest_in_memory 为 0， 即 表示 将 转发 上 游 的 包 体 到 下 游 。 在 5.3.1 
节 中 介绍 过 ， 当 ngx_http_upstream_conf t 结 构 体 中 的 buffering 标 志 位 为 
0 时 ， 意 味 着 以 固定 大 小 的 缓冲 区 来 转发 包 体 。 


static ngx_int_t 
ngx_http_mytest_handler(ngx_http_request_t *r) 
{ 


// 首先 建立 


HTTP 上 下 文 结构 体 


ngx_http_mytest_ctx_t 
ngx_http_mytest_ctx_t* myctx = 

ngx_http_get module ctx(r,ngx_http_mytest_ module); 
if (myctx == NULL) 
{ 


myctx = ngx_palloc(r->pool, sizeof(ngx_http_mytest_ctx_t)); 
if (myctx == NULL) 
{ 


return NGX_ERROR, 


} 
// 将 新 建 的 上 下 文 与 请 求 关联 起 来 


ngx_http_set_ctx(r,myctx,ngx_http_mytest_module); 


} 
/* 对 每 


1 个 要 使 用 


upstream 的 请 求 ， 必 须 调 只 能 调用 


1 次 
ngx_http_upstream_create 方 法 ， 它 会 初始 化 


r->upstream 成 员 


*/ 
If (ngx_http_upstream create(r) != NGX OK) { 
ngx_1log_error(NGX_LOG_ ERR, r->connection->]log, 
0, "ngx_http_upstream create() failed"); 
return NGX_ERROR; 


} 
// 得 到 配置 结构 体 


ngx_http_mytest_conf_t 
ngx_http_mytest_ conf_t *mycf = (ngx_http_mytest _ conf_t *) 
ngx_http_get_ module loc conf(r, ngx_http_mytest module); 
ngx_http_upstream t *u = r->upstream; 
// 这 里 用 配置 文件 中 的 结构 体 来 赋 给 


r->upstream->conf 成 员 


U->conf = &mycf->upstream; 


// 决定 转发 包 体 时 使 用 的 缓冲 区 


u->buffering = mycf->upstream.buffering; 


// 以 下 代码 开始 初始 化 
resolved 结 构 体 ， 用 来 保存 上 游 服 务 器 的 地 址 


U->resolved = (ngx_http_upstream resolved t*) ngx_pcalloc(r->pool, 
sizeof(ngx_http_upstream resolved_t)); 
If (u->resolved == NULL) { 
ngx_1log_error(NGX_LOG_ERR, r->connection->log, 0, 
"ngx_pcalloc resolved error. %s.", strerror(errno)); 
return NGX_ERROR; 


} 
// 这 里 的 上 游 服务 器 就 是 


www.google.com 

static struct sockaddr_in backendSockAddr; 

Struct hostent *pHost = gethostbyname((char*) "www.google.com"); 

if (pHost == NULL) 

{ 
ngx_1log_error(NGX_LOG_ERR, r->connection->log, 0, 

"gethostbyname fail. %s", strerror(errno)); 

return NGX_ERROR; 


} 
// 访问 上 游 服务 器 的 


80 端 


backendSockAddr ,sin_family = AF_INET; 

backendSockAddr ,sin_port = htons((in_ port_t) 80); 

char* pDmsIP = inet_ntoa(*(struct in_addr*) (pHost->h_addr_1list[0])); 
backendSockAddr .sin addr.s_addr = inet_addr(pDmsIP); 
myctx->backendServer.data = (u_char*)pDmsIP; 

myctx->backendServer.len = strlen(pDmsIP); 

// 将 地 址 设置 到 


resolved 成 员 中 


U->resolved->sockaddr = (struct sockaddr *)&backendSockAddr ; 
U->resolved->socklen = sizeof(struct sockaddr_in); 
U->resolved->naddrs = 1; 

// 设 


3 个 必须 实现 的 回调 方法 ， 也 就 是 


3 个 方法 


U->create_request mytest_upstream_create_request 
U->process_header mytest_process_status_ line; 
U->finalize_redquest = mytest_upstream finalize_request; 
// 这 里 必须 将 


count 成 员 加 
1， 参 见 
S545 


r->main->count++; 
// 启动 


upstream 
ngx_http_upstream init(r); 
// 必须 返 世 


NGX_DONE 
return NGX_DONE,; 
} 


到 此 为 止 ， 高 性 能 地 访问 第 三 方 服务 的 upstream 例 子 束 介绍 完 
了 。 在 本 例 中 ， 可 以 完全 异步 地 访问 第 三 方 服务 ， 并 发 访问 数 也 只 会 
受制 于 物理 内 存 的 大 小 ， 完 全 可 以 轻松 达到 几 十 万 的 并 发 TCP 连 接 。 


5.4 ”subrequest 的 使 用 方式 


subrequest 是 由 HTTP 框 架 提供 的 一 种 分 解 复 杂 请 求 的 设计 模式 ， 
它 可 以 把 原始 请 求 分 解 为 许多 子 请 求 ， 使 得 诸多 请 求 协 同 完成 一 个 用 
户 请 求 ， 并 且 每 个 请 求 只 关注 于 一 个 功能 。 它 与 访问 第 三 方 服 务 及 
upstream 机 制 有 什么 关系 呢 ? 站 和 完 ， 只 要 不 是 完全 将 上 游 服 务 器 的 啊 
应 包 体 转发 到 下 游客 户 端 ， 基 本 上 都 会 使 用 subrequest 创 建 出 子 请 求 ， 
并 由 子 请 求 使 用 upstream 机 制 访 问 上 游 服 务 右 ， 然 后 由 父 请 求 根 据 上 
游 啊 应 重 狐 构造 返回 给 下 游客 户 端 的 响应 。 其 次 ， 在 HTTP 框 架 的 设计 
上 ，subrequest 与 upstream 也 是 密切 相关 的 。 例 如 ， 上 文 讲 过 ， 擂 述 
HTTP 请 求 的 ngx_http_request_t 结 构 体 中 有 一 个 标志 位 
subrequest_in_memory， 它 决定 upstream 对 待 上 游 啊 应 包 体 的 行为 。 但 
是 从 名 字 上 我 们 可 以 看 到 ， 它 是 与 subrequest 有 天 的 ， 实 际 上 ， 在 创建 
子 请 求 的 方法 中 就 可 以 设置 subrequest_in_memory。 


subrequest 设 计 的 基础 是 生成 一 个 ( 子 ) 请 求 的 代价 要 非常 小 ， 消 
耗 的 内 存 也 要 很 少 ， 并 且 不 会 一 直 占 用 进程 资源 。 因 此 ， 每 个 请 求 都 
应 该 做 简单 、 独 立 的 工作 ， 而 由 多 个 子 请 求 合 成 为 一 个 父 请 求 向 客户 
端 提供 完整 的 服务 。 在 Nginx 中 ， 大 量 功能 复杂 的 模块 都 是 基于 
subrequest 实 现 的 。 


使 用 subrequest 的 方式 要 比 upstream 人 简单 得 多 ， 只 需要 完成 以 下 4 步 
操作 即 可 。 


一 
Ne 


在 nginx.conf 文 件 中 配置 好 子 请 求 的 处 理 方式 。 


[BS) 
~ 


局 动 subrequest 子 请 求 。 


实现 子 请 求 执行 结束 时 的 回调 方法 。 


CD 
a 


实现 父 请 求 被 油 活 时 的 回调 方法 。 


二 


下 面 依次 说 明 这 4 个 步骤 。 


5.4.1 ”配置 子 请 求 的 处 理 方式 


实际 上 ， 子 请 求 的 处 理 过 程 与 普通 请 求 完全 相同 ， 也 需要 在 
nginx.conf 中 配置 相应 的 模块 来 处 理 。 子 请 求 与 普通 请 求 的 不 同 之 处 在 
于 ， 了 于 请 求 是 由 父 请 求生 成 的 ， 不 是 接收 客户 端 发 来 的 网 络 包 再 由 
HTTP 框 染 解 析出 的 。 配 置 处 理子 请 求 的 模块 与 普通 请 求 完全 相同 ， 可 
以 任意 地 使 用 HTTP 官 方 模块 、 第 三 方 模块 来 处 理 。 本 章 中 将 以 访问 第 
三 方 服务 为 例 ， 因 此 会 使 用 ngx_http_proxy_module 反 向 代理 模块 来 处 
理子 请 求 (注意 ， 这 里 并 没有 使 用 反 疝 代理 的 转发 啊 应 功能 ， 而 只 是 
把 啊 应 接收 到 Nginx 的 内 存 中 ) ， 但 在 实际 应 用 中 不 限于 此 。 


假设 我 们 生成 的 子 请 求 是 以 URI 为 list 开头 的 请 求 ， 使 用 
ngx_http_proxy_module 模 块 让 子 请 求 访 问 新 浪 的 hq.sinajs.cn 股 票 服 务 
器， 那么 可 以 在 nginx.conf 中 这 样 设置 : 


location /list { 
proxy_pass http:// hq.sinajs.cn 


/* 不 希望 第 三 方 服务 发 来 的 


HTTP 包 体 做 过 


gzip 压 缩 ， 因 为 我 们 不 想 在 子 请 求 结束 时 要 对 响应 做 


gzip 解 压缩 操作 


proxy_set_header Accept-Encoding ""; 


这 样 ， 在 5.4.4 节 中 ， 如 果 生 成 的 子 请 求 是 以 /list 开头 的 ， 就 会 使 用 
反 辣 代理 模块 去 访问 新 浪 服 务 絮 ， 并 在 接收 完 新 浪 服 务 絮 的 啊 应 包 后 
调用 5.4.2 市 中 介绍 的 回调 方法 。 


5.4.2 ”实现 子 请 求 处 理 完毕 时 的 回调 方法 


Nginx 在 子 请 求 正 常 或 者 异常 结束 上 时， 都 会 调用 
ngx_http_post_subrequest_pt 回 调 方 法 ， 如 下 所 示 。 


typedef ngx_int_t (*ngx_http_post_ subrequest pt) (ngx_http_request t *r void 
*data, ngx_int_t rc); 


如 何 把 这 个 回调 方法 传递 给 subrequest 子 请 求 呢 ? 要 建立 
ngx_http_post_subrequest_t 结 构 体 : 


typedef struct { 
ngx_http_post_subrequest_pt 
void *data,; 

} ngx_http_post_subrequest_t; 


handler; 


在 生成 ngx_http_post_subrequest_t 结 构 体 时 ， 可 以 把 任意 数据 赋 给 
这 里 的 data 指 针 ，ngx_http_post_subrequest_pt 回 调 方法 执行 时 的 data 参 
数 就 是 ngx_http_post_subrequest_t 结 构 体 中 的 data 成 员 指针 。 


ngx_http_post_subrequest_pt 回 调 方 法 中 的 rc 参数 是 子 请 求 在 结束 
时 的 状态 ， 它 的 取 值 则 是 执行 ngx_http_finalize_request 销 毁 请 求 时 传递 
的 rc 参数 〈 对 于 本 例 来 说 ， 由 于 子 请 求 使 用 反 向 代理 模块 访问 上 游 
HTTP 服 务 器 ， 所 以 rc 此 时 是 HTTP 响应 码 。 例 如 ， 在 正常 情况 下 ，Frc 
会 是 200) 。 相 应 源 代码 如 下 : 


void 
ngx_http_finalize_request(ngx_http_request_t *r, ngx_int_t rc) 


// 如 果 当 前 请 求 属于 某 个 原始 请 求 的 子 请 求 


If (r != r->main && r->post_ subrequest) { 


rc = r->post_subrequest->handler(r, r->post_subrequest->data, rc); 
} 


上 面 代码 中 的 tr 变 量 是 子 请 求 (不 是 父 请 求 ) 。 


在 ngx_http_post_subrequest_pt 回 调 方法 内 必须 设置 父 请 求 激活 后 
的 处 理 方法 ， 设 置 的 方法 很 简单 ， 惠 移 要 找 出 父 请 求 ， 例 如 ; 


ngx_http_request_t *pr = r->parent; 


然后 将 实现 好 的 ngx_http_event_handler_pt 回 调 方法 赋 给 父 请 求 的 
write_event_handler 指 针 (为 什么 设置 write_event_handler? 因为 父 请 求 
正 处 于 等 竺 发 送 响应 的 阶段 ， 详 见 11.7 节 ) ， 例 如 : 


pr->write_event_handler = mytest_post_handler; 


mytest_post_handler 束 是 5.6.4 节 中 实现 的 父 请 求 重新 激活 后 的 回调 
pa 


在 5.6.3 节 中 可 以 看 到 相关 的 具体 例子 。 
5.4.3 ”处 理 父 请 求 被 重新 激活 后 的 回调 方法 


mytest_post_handler 是 父 请 求 重新 激活 后 的 回调 方法 ， 它 对 应 于 
ngx_http_event_handler_pt 指 针 ， 如 下 所 示 : 


typedef void (*ngx_http_event_handler_pt)(ngx_http_request t *r); 
struct ngx_http_request_Ss { 


ngx_http_event_handler_pt write_event_handler 


这 个 方法 负责 发 送 啊 应 包 给 用 户 ， 其 流程 与 3.7 市 中 介绍 的 发 送 方 
式 是 一 致 的 ， 也 可 以 参考 5.6.4 节 中 的 例子 。 


5.4.4 ”局 动 subrequest 子 请 求 


在 ngx_http_mytest_handler 处 理 方法 中 ， 可 以 启动 subrequest 子 请 
求 。 首 先 调 用 ngx_http_subrequest 方 法 建立 subrequest 子 请 求 ， 在 
ngx_http_mytest_handler 返 回 后 ，HTTP 框 架 会 自动 执行 子 请 求 。 先 看 


一 下 ngx_http_subrequest 的 定义 : 


ngx_int_t 

ngx_http_subrequest(ngx_http_request _t *r, 
ngx_str_t *uri, ngx_str_t *args, ngx_http_request t **psr, 
ngx_http_post_subrequest_t *ps, ngx_uint_t flags); 


下 面 依次 介绍 ngx_http_subrequest 中 的 参数 和 返回 值 。 
(1) ngx_http_request_tsr 


ngx_http_request_t*r 是 当前 的 请 求 ， 也 就 是 父 请 求 。 


(2) ngx_str_t*uri 


ngx_str_t*uri 是 子 请 求 的 URI， 它 对 究竟 选用 nginx.conf 配 置 文 件 中 
的 哪个 模块 来 处 理子 请 求 起 决定 性 作用 。 


(3) ngx_str_t*args 

ngx_str_t*args 是 子 请 求 的 URI 参 数 ， 如 果 没 有 参数 ， 可 以 传送 
NULL 空 指针 。 

(4) ngx_http_request_t**psr 


psr 是 输出 参数 而 不 是 输入 参数 ， 它 将 把 ngx_http_subrequest 生 成 
的 子 请 求 传 出 来 。 一 般 ， 我 们 先 建立 一 个 子 请 求 的 空 指针 
ngx_http_request_t*psr， 再 把 它 的 地 址 &psr 传 入 到 ngx_http_subrequest 
方法 中 ， 如 果 ngx_http_subrequest 返 回 成 功 ，psr 就 指向 建立 好 的 子 请 


(5) ngx_http_post_subrequest_t*ps 


这 里 传 入 5.4.2 广 中 创建 的 ngx_http_post_subrequest_t 结 构 体 地 址 ， 
它 指 出 子 请 求 结束 时 必须 回调 的 处 理 方法 。 


(6) ngx_uint_t flags 


flag 的 取 值 范围 包括 : (V0。 在 没有 特殊 需求 的 情况 下 都 应 该 填写 
它 ;，@NGX_HTTP_SUBREQUEST_IN_MEMORY。 这 个 宏 会 将 子 请 求 


的 subrequest_in_memory 标 志 位 置 为 1， 这 意味 着 如 果子 请 求 使 用 
upstream 访 问 上 游 服务 各， 那么 上 族 服 务 器 的 啊 应 都 将 会 在 内 存 中 处 
理 ; @NGX_HTTP_ SUBREQUEST WAITED。 这 个 宏 会 将 子 请 求 的 
waited 标 志 位 置 为 1， 当 子 请 求 提 前 结束 时 ， 有 个 done 标 志 位 会 置 为 
1,， 但 目前 HTTP 框 架 并 没有 针对 这 两 个 标志 位 做 任何 实质 性 处 理 。 注 
意 ，flag 是 按 比 特 位 操作 的 ， 这 样 可 以 同时 含有 上 述 3 个 值 。 


(7) 返回 值 


返回 NGX_OK 表 示 成 功 建立 子 请 求 ; 返回 NGX_ERROR 表 示 建 立 
子 请 求 失败 。 


ngx_http_mytest_handler 处 理 方法 的 返回 值 依然 与 upstream 机 制 相 
同 ， 它 也 必须 返回 NGX_DONE， 原 因 也 是 相同 的 。 


5.5 ”subrequest 执 行 过 程 中 的 主要 场景 


在 使 用 subrequest 时 ， 需 要 了 解 下 面 3 个 场景 : 

:启动 subrequest 后 子 请 求 是 如 何 运 行 的 。 

于 请 求 如 何 存 放 接收 到 的 啊 应 。 

子 请 求 结束 时 如 何 回调 处 理 方法 ， 以 及 激活 父 请 求 的 处 理 方 法 。 
下 面 根据 序列 图 来 说 明 这 3 个 场景 。 


5.5.1 ”如 何 启 动 subrequest 


人 处理 父 请 求 的 过 程 中 会 创建 子 请 求 ， 在 父 请 求 的 处 理 方法 返回 
NGX_DONE 后 ，HTTP 框 架 会 开始 执行 子 请 求 ， 如 图 5-6 所 示 。 


下 面 简 单 介 绍 一 下 图 5-6 中 的 每 一 个 步 又 : 


1) Nginx 主 循环 中 会 定期 地 调用 事件 模块 ， 检 查 是 否 有 网 络 事件 
发 生 。 


2) 事件 模块 发 现 这 个 请 求 的 回调 方法 属于 HTTP 框 架 ， 交 由 HTTP 
框架 来 处 理 请 求 。 


3) 根据 解析 完 的 URI 来 决定 使 用 哪个 location 下 的 模块 来 处 理 这 个 
请 求 。 
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图 5-6 ”subrequest 的 启动 过 程序 列 图 
4) 调用 mytest 模 块 的 ngx_http_mytest_handler 方 法 处 理 这 个 请 求 。 


5) 设置 subrequest 子 请 求 的 URI 及 回调 方法 ， 这 一 步 以 及 下 面 的 第 
6~9 步 所 做 的 工作 参见 5.4.4 斑 。 


6) 调用 ngx_http_subrequest 方 法 创建 子 请 求 。 


7) 创建 的 子 请 求 会 添加 到 原始 请 求 的 posted_requests 链 表 中 ， 这 
样 保证 第 10 步 时 会 在 父 请 求 返回 NGX_DONE 的 情况 下 开始 执行 子 请 
求 o 


8) ngx_http_subrequest 方 法 执行 完毕 ， 子 请 求 创 建成 功 。 


9) ngx_http_mytest_handler 方 法 执行 完毕 ， 返 回 NGX_DONE， 这 
样 父 请 求 不 会 被 销毁 ， 将 等 待 以 后 的 再 次 激活 。 


10) HTTP 框 架 执 行 完 当 前 请 求 〈 父 请 求 ) 后 ， 检 查 
posted_requests 链 表 中 是 否 还 有 子 请 求 ， 如 果 存 在 子 请 求 ， 则 调用 子 请 
求 的 write_event_handler 方 法 ( 详 见 11.7 节 ) 


11) 根据 子 请 求 的 URI 〈 第 5 步 中 建立 ) ， 检 查 nginx.conf 文 件 中 所 
有 的 location 配 置 ， 确 定 应 由 哪个 模块 来 执行 子 请 求 。 在 本 章 的 例子 
中 ， 子 请 求 是 交 由 反 疝 代理 模块 执行 的 。 


12) 调用 反 辣 代理 模块 的 入 口 方法 ngx_http_proxy_handler 来 处 理 


13) 由 于 反 向 代理 模块 使 用 了 upstream 机 制 ， 所 以 它 也 要 通过 许多 
次 的 异步 调用 才能 完整 地 处 理 完 子 请 求 ， 这 时 它 的 入 口 方法 会 返回 
NGX_DONE (非常 类 似 5.1.5 节 中 的 内 容 ) 。 


14) 再 次 检查 是 否 还 有 子 请 求 ， 这 时 会 发 现 已 经 没有 子 请 求 需要 
执行 了 。 当 然 ， 子 请 求 可 以 继续 建立 新 的 子 请 求 ， 只 是 这 里 的 反 向 代 
理 模块 不 会 这 样 做 。 


15) 当 第 2 步 中 的 网 络 读 取 事件 处 理 完毕 后 ， 交 还 控制 权 给 事件 模 
块 。 


16) 当 本 轮 网 络 事 件 处 理 完毕 后 ， 交 还 控制 权 给 Nginx 主 循环 。 


5.5.2 ”如 何 转 发 多 个 子 请 求 的 啊 应 包 体 


ngx_http_postpone _filter_ module 过 滤 模 块 实际 上 是 为 了 subrequest 
功能 而 建立 的 ， 本 章 的 例子 虽然 没有 用 到 postpone (能 够 应 用 到 的 场合 
其 实 非 常 少 ，， 这 里 还 是 要 介绍 一 下 这 个 过 滤 模 块 希 望 解决 什么 样 的 
问题 ， 这 样 读者 会 对 postpone 模 块 和 subrequest 间 的 关系 有 更 深刻 的 了 
解 。 


当 派 生 一 个 子 请 求 访问 第 三 方 服务 时 ， 如 琳 只 是 布 望 接收 到 完整 
的 啊 应 后 在 Nginx 中 解析 、 人 处理， 那么 这 里 丈 不 需要 postpone 模 块 ， 就 
像 5.6 节 中 的 例子 那样 处 理 即 可 ;如 果 原 始 请 来 派生 出 许多 子 请 求 ， 并 
且 和 希望 将 所 有 子 请 求 的 啊 应 依次 转发 给 客户 病 ， 当 然 ， 这 里 的 * 依 
次 ” 束 是 按照 创建 子 请 求 的 顺序 来 发 送 啊 应 ， 这 时 ，postpone 模 块 就 有 
了 “用 武之 地 ”。Nginx 中 的 所 有 请 求 都 是 异步 执行 的 ， 后 创建 的 子 请 求 
可 能 优先 执行 ， 这 样 转 发 到 客户 端的 响应 束 会 产生 混乱 。 而 postpone 模 
块 会 强制 地 把 行 较 发 的 啊 应 包 体 放 在 一 个 链表 中 发 送 ， 只 有 优先 转发 
的 于 请 求 结束 后 才 会 开始 转发 下 一 个 子 请 求 中 的 啊 应 。 下 面 介绍 一 下 
它 征 如何 实 现 的 。 


每 个 请 求 的 ngx_http_request_t 结 构 体 中 都 有 一 个 postponed 成 员 : 
struct ngx_http_request _s { 


ngx_http_postponed_request_t *postponed; 


开 实 际 上 古 一 个 链表 : 


typedef struct ngx_http_postponed request_s ngx_http_postponed request_t; 
struct ngx_http_postponed request s { 


ngx_http_request_t *request,; 
ngx_chain_t *out; 
ngx_http_postponed_request_t *next,; 


}; 


从 上 述 代 码 可 以 看 出 ， 多 个 ngx_http_postponed_request_t 之 间 使 用 
next 指 针 连 接 成 一 个 单 癌 链表。ngx_http_postponed_request_t 中 的 out 成 
ngx_chain_t 结 构 ， 它 指向 的 是 米 自 上 游 的 、 将 要 转发 给 下 游 的 啊 


日 
人 AE 
VY 包 体 。 


每 当 使 用 ngx_http_output_filter 方 法 ( 反 向 代理 模块 也 使 用 该 方法 
转发 响应 ) 向 下 游 的 客户 端 发 送 啊 应 包 体 时 ， 都 会 调用 到 
ngx_http_postpone_filter_ module 过 滤 模 块 处 理 这 段 要 发 送 的 包 体 。 下 面 
看 一 下 过 滤 包 体 的 ngx_http_postpone_filter 方 法 (在 阅读 完 第 11 章 后 再 
回头 看 这 段 代 码 ， 概 念 可 能 会 更 加 请 晰 ) : 


// 这 里 的 参数 


in 就 是 将 要 发 送 给 客户 端的 一 段 包 体 ， 第 


6 章 会 详 述 


HTTP 过 滤 模 块 


static ngx_int_t 
ngx_http_postpone_filter(ngx_http_request_t *r, ngx_chain_t *in) 


ngx_connection_t *C) 
ngx_http_postponed_request t *pr; 
// c 是 


Nginx 与 下 游客 户 端 间 的 连接 ， 
c->data 保 存 的 是 原始 请 求 


c = r->connection; 


// 如 果 当 前 请 求 


r 症 一 个 于 请 求 (因为 


c->data 指 向 原始 请 求 ) 


if I!= c->data) { 
/* 如 果 待 发 送 的 


in 包 体 不 为 空 ， 则 把 


in 加 到 


postponed 链 


中 属于 当前 请 求 的 


ngx_http_postponed_request_t 结 构 体 的 


瑟 


out 链 表 中 ， 同 时 返 
NGX_0K， 这 意味 着 本 次 不 会 把 
in 包 体 发 给 客户 端 


*/ 


if (in) { 
ngx_http_postpone_filter add(r，in)，; 
return NGX_OK， 


// 如 果 当 前 请 求 是 子 请 求 ， 而 


in 包 体 又 为 空 ， 那 么 直接 返回 即 可 


return NGX_oKk; 
} 
// 如 果 
postponed 为 空 ， 表 示 请 求 


r 没 有 子 请 求 产生 的 响应 需要 转发 


if (r->postponed == NULL) { 
/* 直 接 调用 下 一 个 


HTTP 过 滤 模 块 继续 处 理 


in 包 体 即 可 。 如 果 没 有 错误 的 话 ， 就 会 开始 向 下 游客 户 端 发 送 啊 应 


*/ 
if (in || c->buffered) { 
return ngx_http_next_filter(r->main, in); 
} 
return NGX_OK， 
} 
/* 至 此 ， 说 明 


postponed 链 表 中 是 有 子 请 求 产生 的 响应 需要 转发 的 ， 可 以 先 把 
in 包 体 加 到 待 转发 响应 的 末尾 
* 
if (in) { 
ngx_http_postpone_filter _ add(r, in); 
} 
// 循环 处 理 


postponed 链 表 中 所 有 子 请 求 待 转 发 的 包 体 


do { 


pr = r->postponed,; 
/* 如 果 时 


pr->request 是 子 请 求 ， 则 加 入 到 原始 请 求 的 


posted_requests 队 列 中 ， 等 待 


HTTP 框 架 下 次 调用 这 个 请 求 时 再 来 处 理 ( 参 


11.7 节 ) 
*/ 
if (pr->request) { 
r->postponed = pr->next; 
c->data = pr->request,; 
return ngx_http_post_request(pr->request, NULL); 
} 
// 调用 下 一 个 
HTTP 过 滤 模 块 转发 


out 链 表 中 保存 的 待 转发 的 包 体 


If (pr->out == NULL) { 
} else { 
If (ngx_http_next_filter(r->main, pr->out) == NGX_ERROR) { 
return NGX_ERROR; 
} 


} 
// 遍历 完 


postponed 链 表 


r->postponed = pr->next; 
} while (r->postponed); 
return NGX_OK， 


图 5-7 展 示 了 使 用 反 回 代理 模块 转发 子 请 求 的 包 体 的 一 般 流 程 ， 其 
中 的 第 5 步 正 是 上 面 介 绍 的 ngx_http_postpone_filter 方 法 。 


下 面 简单 地 介绍 一 下 图 5-7 中 的 每 一 个 步 又 : 


1) Nginx 主 循环 中 会 定期 地 调用 事件 模块 ， 检 查 是 否 有 网 络 事件 
发 生 。 


2) 事件 模块 发 现 这 个 请 求 的 回调 方法 属于 反 向 代理 模块 的 接收 
HTTP 包 体 阶 段 ， 于 是 交 由 反问 代理 模块 来 处 理 。 


3) 读 取 上 游 服 务 器 发 来 的 包 体 。 


4) 对 于 接收 到 的 字符 流 ， 会 依次 调用 所 有 的 HITP 过 滤器 模块 来 
转发 包 体 。 其 中 ， 还 会 调用 到 postpone 过 滤 模 块 ， 这 个 模块 将 会 处 理 设 


置 在 子 请 求 中 的 ngx_http_postponed_request_ t 链 表 。 


5) postpone 模 块 使 用 ngx_http_postpone_filter 方 法 将 待 转发 的 包 体 
以 合适 的 顺序 再 进行 整理 发 送 到 下 游客 户 端 。 如 果 
ngx_http_postpone_filter 方 法 没有 通过 ngx_http_next_filter 方 法 继续 调用 
其 他 HTTP 过 滤 模 块 (如 由 于 顺序 的 原因 而 暂停 转发 某 个 子 请 求 的 响应 
包 体 ) ， 将 会 直接 跳 到 第 7 步 ， 否 则 继续 处 理 这 段 接收 到 的 包 体 (第 6 
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postpone 过 滤 杭 块 
1. 检查 是 否 有 网 络 事件 


| 、 PE sk ~ |- 
2. 回调 当前 读 事件 的 处 理 方法 


,> 3. 读 取 上 游 发 来 的 响应 


4. 调用 postpone 过 滤 模 块 处 理 接收 到 的 字符 流 


Wi 5. 根据 当前 子 请 求 的 状态 | 油 整 待 转发 的 响应 包 体 


6. 继续 调用 其 他 过 滤 需 ， 全 部 执行 完 后 返回 
El = 
| 
| 
7. 交还 控制 权 给 事 件 模块 
| | 
8. 本 次 网 络 事件 处 理 完 
< 一 PT | Rn i EY A | a 
| | | | 


图 5-7 子 请 求 转发 HTTP 包 体 过 程 的 序列 图 


6) 继续 调用 其 他 HTTP 过 滤 模 块 ， 待 所 有 的 过 滤 模 块 执 行 完 毕 后 
将 控制 权 交 还 给 反 向 代理 模块 。 


7) 当 第 2 步 中 的 网 络 读 取 事件 处 理 完毕 后 ， 交 还 控制 权 给 事件 模 
块 。 


8) 当 本 轮 网 络 事 件 处 理 完毕 后 ， 交 还 控制 权 给 Nginx 主 循环 。 


5.5.3” 子 请 求 如 何 激活 父 请 来 


子 请 求 在 结束 前 会 回调 在 ngx_http_post_subrequest_t 中 实现 的 
handler 方 法 ( 见 5.4.2 节 ) ， 在 这 个 handler 方 法 中 ， 又 设置 了 父 请 求 被 
激活 后 的 执行 方法 mytest_post_handler， 流 程 如 图 5-8 所 示 。 


下 面 人 简单 地 介绍 一 下 图 5-8 中 的 每 一 个 步 又 : 


1) Nginx 主 循环 中 会 定期 地 调用 事件 模块 ， 检 查 是 否 有 网 络 事件 
发 生 。 


2) 如 果 事 件 模 块 检测 到 连接 关闭 事件 ， 而 这 个 请 求 的 处 理 方法 属 
于 upstream 模 块 ， 则 交 由 upstream 模 块 来 处 理 请 求 。 


3) upstream 模 块 开 始 调用 ngx_http_upstream_finalize_request 方 法 来 
结束 upstream 机 制 下 的 请 求 ( 详 见 12.9 节 ) 


| 
|. 检查 是 否 有 网 络 事件 。 “1 
1 


| 
2 .回调 当前 连接 关闭 事件 的 处 理 函数 


es 
We 3 ed le 


4 . finalize 销毁 子 请 求 
EE 
法 


| 


i |， 


5. 回调 子 请 求 的 处 理 


过 


6. 解 析 子 请 求 的 响应 , 并 设置 父 请 求 的 回调 方法 


em | 


8. finalize 执行 完 


了 :六 用 水 加 网 采信 VT 


14. 事件 处 理 完毕 、 


图 5-8 子 请 求 激活 父 请 求 过程 的 序列 图 


4) 调用 HTTP 框 架 提 供 的 ngx_http_finalize_request 方 法 来 结束 子 请 


5) ngx_http_finalize_request 方 法 会 检查 当前 的 请 求 是 否 是 子 请 
求 ， 如 果 是 子 请 求 ， 则 会 回调 post_subrequest 成 员 中 的 handler 方 法 ( 参 
见 图 11-26 中 的 第 5 步 ) ， 也 就 是 会 调用 mytest_subrequest_post_handler 
方法 SO 


dS 


6) 在 实现 的 子 请 求 回调 方法 中 ， 解 析 子 请 求 返 回 的 响应 包 
意 ， 这 时 需要 通过 write _event_handler 设 置 父 请 求 被 激活 后 的 回调 方法 
(因为 此 时 父 请 求 的 回调 方法 已 经 被 HTTP 框 架设 置 为 什么 事 都 不 做 的 
ngx_http_request_empty_handler 方 法 ， 详 见 第 11 章 ) 。 


7) 了 于 请 求 的 回调 方法 执行 完毕 后 ， 交 由 HTTP 框 架 的 
ngx_http_finalize_request 方 法 继续 癌 下 执行 。 


8) ngx_http_finalize_request 方 法 执行 完毕 。 


9) HTTP 框 架 如 果 发 现 当 前 请 求 后 还 有 父 请 求 需要 执行 ， 则 调用 
父 请 求 的 write _event_handler 回 调 方法 。 


10) 这 里 可 以 根据 第 6 步 中 解析 子 请 求 响 应 后 的 结果 来 构造 响应 


ay 


11) 调用 无 阻塞 的 ngx_http_send_header、ngx_http_output_filter 发 
送 方法 ， 回 客户 端 发 送 啊 应 包 


12) 无 阻塞 发 送 方法 会 立刻 返回 。 即 使 目前 未 发 送 完 ，Nginx 之 后 
也 会 异步 地 发 送 完 所 有 的 响应 包 ， 然 后 再 结束 请 求 。 


13) 父 请 求 的 回调 方法 执行 完毕 。 


14) 当 第 2 步 中 的 上 游 服务 器 连接 关闭 事件 处 理 完毕 后 ， 交 还 控制 
权 给 事件 模块 。 


15) 当 本 轮 网 络 事件 处 理 完毕 后 ， 交 还 控制 权 给 Nginx 主 循环 。 


5.6 ”subrequest 使 用 的 例子 


下 面 以 一 个 简单 的 例子 说 明 subrequest 的 用 法 。 场 景 很 简单 ， 当 使 
用 浏览 器 访问 /query?s_sh000001 时 (s_sh000001 是 新 浪 服务 器 上 的 A 股 
上 证 指数 ) ，Nginx 由 mytest 模 块 处 理 ， 它 会 生成 一 个 子 请 求 ， 由 反 向 
代理 模块 处 理 这 个 子 请 求 ， 访 问 新 浪 的 http:/hq.sinajs.cn 服务 器 ， 这 时 
子 请 求 得 到 的 响应 包 是 上 证 指数 的 当天 价格 交易 量 等 信息 ， 而 mytest 
模块 会 解析 这 个 响应 ， 重 新 构造 发 往 客户 端 浏览 器 的 HITP 响 应 。 浏 览 
器 得 到 的 返回 值 格式 为 : stock[ 上 证 指数 ]，Today current 
price:2373.436,volumn:770。 当 然 ， 如 果 传 入 的 参数 不 仅 是 
s_sh000001， 也 可 以 是 任意 新 良 服 务 器 识别 的 股票 代码 ， 如 
s_sh000009 代 表 上 证 380。 


这 个 例子 说 明 如 何 生成 子 请 求 ， 以 及 子 请 求 如 何 通 过 配置 文件 配 
置 为 反 疝 代理 服务 器 以 访问 新 浪 ， 并 试图 将 新 浪 的 返回 内 容 全 部 保存 
在 一 块 内 存 缓冲 区 中 ， 最 后 解析 缓冲 区 中 的 内 容 生 成 HTTP 响 应 返回 给 
浏览 稻 等 过 程 。 这 里 的 限制 条 件 是 内 存 缓冲 区 的 大 小 要 可 以 容纳 完整 
的 新 浪 服 务必 的 啊 应 ， 它 实际 上 是 由 ngx_http_upstream_conf t 结 构 体 
内 的 buffer_size 参 数 决定 的 〈 见 5.3.1 节 ) ， 而 对 于 反问 代理 模块 来 说 ， 
就 是 由 nginx.conf 文 件 中 的 proxy_buffer_size 配 置 项 决定 的 。 如 果 新 浪 
这 样 的 上 游 服务 器 返回 的 HTTP 啊 应 大 于 缓冲 区 大 小 ， 请 求 将 会 出 错 ， 


这 时 要 么 增 大 proxy_buffer_size 配 置 的 值 ， 要 么 不 能 再 选择 反 回 代理 模 
块 访问 上 游 服务 器 ， 而 要 上 自己 使 用 upstream 机 制 编写 相应 的 HTTP 模 块 
解析 上 游 服 务 右 的 啊 应 包 体 。 


5.6.1 配置 文件 中 子 请 求 的 设置 


若 访 问 新 浪 服务 器 的 URL 为 /list=s_sh000001， 则 可 以 这 样 配 置 : 


location /list 


{ 
// 决定 访问 的 上 游 服务 器 地 址 是 


hq.sinajs.cn 
proxy_pass http://hq.sinajs.cn 


// 不 希望 第 三 方 服务 发 来 的 


HTTP 包 体 进 行 过 


gzip 压 缩 


proxy_set_header Accept-Encoding  "" 


当然 ， 处 理 以 /query 开 头 的 URI 用 户 请 求 还 需 选 用 mytest 模 块 ， 例 
如 : 


location /query { 
mytest ， 
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这 里 的 上 下 文 仅 用 于 保存 子 请 求 回 调 方法 中 解析 出 来 的 股票 数 
据 ， 如 下 所 示 : 


typedef struct { 
ngx_str_t stock[6]; 


} ngx_http_mytest_ctx_t; 


新 浪 服 务 右 的 返回 大 人 致 如 下 : 


var hq_str_s_sh900009=" 上 证 


380,3356.355, -5.725, -0.17,266505, 2519967"; 


上 段 代 码 中 引号 内 的 6 项 值 (以 逗号 分 隔 ) 就 是 解析 出 的 值 。 在 父 
请 求 的 回调 方法 中 ， 将 会 用 到 这 6 个 值 。 


5.6.3 “了 请求 结 束 时 的 处 理 方法 


定义 mytest_subrequest_post_handler 作 为 子 请 求 结束 时 的 回调 方 
法 ， 如 下 所 示 : 


static ngx_int_t mytest_ subrequest _ post handler(ngx_http_request t *r, 
void *data, ngx_int _t rc){ 
// 当前 请 求 


r 是 子 请 求 ， 它 的 
parent 成 员 指向 父 请 求 


ngx_http_request_t *pr = r->parent; 


r 
/* 注 意 ， 由 于 上 下 文 是 保存 在 父 请 求 中 的 (参见 


和 已 


5.6.5 节 ) ， 所 以 要 由 
pr 取 上 下 文 。 其 实 有 更 简单 的 方法 ， 即 参数 


data 就 是 上 下 文 ， 初 始 化 


subreduest 时 就 对 其 进行 设置 。 这 里 仅 为 了 说 明 如 何 获取 到 父 请 求 的 上 下 文 


*/ 
ngx_http_mytest_ctx_t* myctx = 

ngx_http_get_ module ctx(pr,ngx_http_mytest_module); 
pr->headers out,.status = r->headers out.status,; 
/* 如 果 返 回 


NGX_HTTP_OK (也 就 是 
200) ， 则 意味 着 访问 新 浪 服务 器 成 功 ， 接 着 将 开始 解析 
HTTP 包 体 


4 
If (r->headers_out,status == NGX_HTTP_OK) 


int flag = 0; 
/* 在 不 转发 响应 时 ， 


buffer 中 会 保存 上 游 服务 器 的 响应 。 特 别 是 在 使 用 反 向 代理 模块 访问 上 游 服务 器 时 ， 如 果 它 使 用 


upstream 机 制 时 没有 重 定义 


input_filter 方 法 ， 

upstream 机 制 默认 的 

input_filter 方 法 会 试图 把 所 有 的 上 游 响 应 全 部 保存 到 
区 中 


buffer 绥 ; 


5 
ngx_buf_t* pRecvBuf = &r->upstream->buffer ， 


/* 以 下 开始 解析 上 游 服 务 器 的 响应 ， 并 将 解析 出 的 值 赋 到 上 下 文 结构 体 


myctx->stock 数 组 中 


6 
for (;pRecvBuf->pos != pRecvBuf->last; pRecvBuf->pos++) 
if (*pRecvBuf->pos == ',' || *pRecvBuf->pos == '\"') 
if (flag > 0) 
{ 
myctx->stock[flag-1].len = pRecvBuf->pos-myctx->stock[flag- 
1].data; 
上 
flag++; 


myctx->stock[flag-1].data = pRecvBuf->pos+1; 


} 
if (flag > 6) 
break; 


} 
// 设置 接 下 来 父 请 求 的 回调 方法 ， 这 一 步 很 重要 


pr->write_event_handler = mytest_post_handler; 


return NGX_OK; 


5.6.4 父 请 求 的 回调 方法 


将 父 请 求 的 回调 方法 定义 为 mytest_post_handler， 如 下 所 示 : 


static void 
mytest_post_handler(ngx_http_request _t *r) 


// 如 果 没 有 返 下 


下 


200， 则 直接 把 错误 码 发 


if (r->headers_out,status != NGX_HTTP_OK) 


ngx_http_finalize_request(r，r->headers_out .status ) ， 
return; 

} 和 、 稚 、 二 

// 当前 请 求 是 父 请 求 ， 直 接 取 其 上 下 文 


ngx_http_mytest_ctx_t* myctx = 
ngx_http_get_ module ctx(r,ngx_http_mytest_module); 
/* 定 义 发 给 用 户 的 


HTTP 包 体内 容 ， 格 式 为 : 
Stock[.… 
],Today current price: .. 
; Volumn: 
*/ 
ngx_str_t output_ format = ngx_string("stock[%V],Today current price: %V， 


volumn: %V"); 


// 计算 待 发 送 包 体 的 长 度 


int bodylen = output_format .Jen + myctx->stock[0].1len 
+myctx->stock[1].len+myctx->stock[4].len-6; 
r->headers_out.content_length_n = bodylen,; 


// 在 内 存 池 上 分 配 内 存 以 保存 将 要 发 送 的 包 体 


ngx_buf_t* b = ngx_create temp_buf(r->pool, bodylen); 

ngx_snprintf(b->pos, bodylen, (char*)output_format.data, 
&myctx->stock[0],&myctx->stock[1],&myctx->stock[4]); 

b->last = b->pos + bodylen,; 

b->last_buf = 1; 


ngx_chain_t out 


out .buf = b; 
out .next = NULL; 
// 设 


Content -Type， 注 意 ， 在 汉字 编码 方面 ， 新 浪 服务 器 使 用 了 


GBK 
static ngx_str_t type = ngx_string("text/plain; charset=GBK"); 
r->headers_out.content_type = type; 
r->headers_out.status = NGX_HTTP_OK; 
r->connection->buffered |= NGX_HTTP_WRITE_BUFFERED ， 
ngx_int_t ret = ngx_http_send_header(r); 
ret = ngx_http_output_filjter(r, &out); 

/* 注 意 ， 这 里 发 送 完 响应 后 必须 手动 调 


ngx_http_finalize_request 结 束 请 求 ， 因 为 这 时 


HTTP 框 架 不 会 再 帮忙 调用 它 


*/ 


} 


ngx_http_finalize_request(r, ret); 


5.6.5 ”局 动 subrequest 


在 处 理 用 户 请 求 的 ngx_http_mytest_handler 方 法 中 ， 开 始 创 建 
subrequest 子 请 求 。ngx_http_mytest_handler 方 法 的 完整 实现 如 下 所 示 : 


static ngx_int_t 
ngx_http_mytest_handler(ngx_http_request_t *r) 


// 创建 
HTTP 上 下 文 


ngx_http_mytest_ctx_t* myctx = 
ngx_http_get_ module ctx(r,ngx_http_mytest_module); 
if (myctx == NULL) 
{ 
myctx = ngx_palloc(r->pool, sizeof(ngx_http_mytest_ ctx_t)); 
if (myctx == NULL) 


return NGX_ERROR; 


} 
// 将 上 下 文 设置 到 原始 请 求 
r 中 


ngx_http_set_ctx(r,myctx,ngx_http_mytest_module); 


} 
// ngx_http_post_subrequest_t 结 构 体 会 决定 子 请 求 的 回调 方法 ， 参 见 
5.4.1 节 


ngx_http_post_subrequest_t *psr = ngx_palloc(r->pool, 
sizeof(ngx_http_post_subrequest_t)); 
If (psr == NULL) { 
return NGX_HTTP_INTERNAL_ SERVER_ERROR, 
} 


// 设置 子 请 求 


bs] 


调 方 法 为 


mytest_subrequest_post_handler 
psr->handler = mytest_subrequest_post_handler; 
/* 将 

data 设 为 


myctx 上 上 下文， 这样 回 调 


mytest_subrequest_post_handler 时 传 入 的 
data 参 数 就 是 
myctx*/ 
psr->data = myctx; 
/* 子 请 求 的 
URI 前 级 


是 
/List， 这 是 因为 访问 新 浪 服 务 器 的 请 求 必须 是 类 似 


/1ist=s_sh000001 的 


URI， 这 与 在 


nginx.conf 中 配置 的 子 请 求 
location 的 


URI 是 一 致 的 ( 见 


二 上 
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*/ 
ngx_str_t sub_prefix = ngx_string("/list="); 
ngx_str_t sub_location; 
Sub_Jlocation,len = sub_prefix.len + r->args.1len; 
sub_location,.data = ngx_palloc(r->pool, sub_location.1len); 
ngx_snprintf(sub_location.data, sub_location.len, 
"%V%V", &sub_prefix,e&r->args); 
// sr 就 是 子 请 求 


ngx_http_request_t *sr,; 
/* 调 


ngx_http_subrequest 创 建 子 请 求 ， 它 只 会 返回 


NGX_OK 或 者 


NGX_ERROR。 返 回 


NGX_OK 时 ， 


sr 已 经 是 合法 的 子 请 求 。 注 意 ， 这 里 的 


NGX_HTTP_SUBREQUEST_IN_MEMORY 参 数 将 告诉 


upstream 模 块 把 上 游 服务 器 的 响应 全 部 保存 在 子 请 求 的 


sr->upstream->buffer 内 存 缓冲 区 中 


*/ 
ngx_int_t rc = ngx_http_subrequest(r, &sub_location, NULL, &sr, psr, 
NGX_HTTP_SUBREQUEST_IN_MEMORY ) ， 
if (rc != NGX_OK) { 
return NGX_ERROR ， 


} 
// 必须 返 区 


NGX_DONE， 原 因 同 


upstream 
return NGX_DONE,; 
} 


至 此 ， 一 个 使 用 subrequest 的 mytest 模 块 已 经 创建 完成 ， 它 支持 的 
并 发 HTTP 连 接 数 只 与 物理 内 存 大 小 相关 ， 因 此 ， 这 样 的 服务 硕 通 常 可 
以 轻易 地 文 持 儿 十 万 的 并 发 TCP 连 接 。 
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反 回 代理 是 Nginx 布 望 实现 的 一 大 功能 。 从 本 章 的 内 容 中 可 以 感受 
到 ，upstream 和 subrequest 部 为 转发 上 游 服 务 占 的 啊 应 做 了 大 量 工 作 ， 
当然 ，upstream 的 转发 过 程 也 非常 高 效 。 然 而 ， 转 发 啊 应 毕竟 只 是 访 
问 第 三 方 服务 的 一 种 应 用 ， 而 upstream 最 初始 的 目的 就 是 用 于 访问 上 
游 服务 器 。 本 章 前 半 部 分 虽然 以 转发 啊 应 为 例 说 明了 upstream 的 一 种 
使 用 方式 ， 但 后 半 部 分 创建 的 子 请 求 却 是 通过 反 回 代理 模块 使 用 
upstream 将 上 游 服 务 器 简单 地 保存 在 内 存 中 的 。 天 于 upstream 更 详细 的 
用 法 ， 将 在 第 12 半 讲述。subrequest 是 分 解 复杂 请 求 的 设计 方法 ， 派 生 
出 的 子 请 求 使 用 某 些 HTTP 模 块 基于 upstream 访 问 第 三 方 服务 是 最 常见 
的 用 法 。 通 过 subrequest 可 以 使 Nginx 在 保持 高 并 发 的 前 提 下 处 理 复 杂 
的 业务 。 


当 应 用 需要 访问 第 三 方 服务 时 ， 可 以 根据 以 上 特性 选择 使 用 
upstream 或 者 subrequest， 它 们 可 以 完全 地 发 挥 Nginx 原 生 的 高 并 发 特 
性 ， 支 持 现 代 互 联网 服务 器 中 海量 数据 的 处 理 。 


第 6 章 ”开发 一 个 简单 的 HITP 过 着 模块 


本 章 开 始 介绍 如 何 开发 HITP 过 滤 模 块 。 顾 名 思 义 ，HTTP 过 滤 模 
块 也 是 一 种 HTTP 模 块 ， 所 以 第 3 章 中 讨论 过 的 如 何 定义 一 个 HTTP 模 块 
以 及 第 4 章 中 讨论 的 使 用 配置 文件 、 上 下 文 、 日 志 的 方法 对 它 来 说 都 是 
适用 的 。 事 实 上 ， 开 发 HTTP 过 滤 模 块 用 到 的 大 部 分 知识 在 第 3 草 和 第 4 
章 中 都 已 经 介绍 过 了 ， 只 不 过 ，HTTP 过 滤 模 块 的 地 位 、 作 用 与 正常 的 
HTTP 处 理 模 块 是 不 同 的 ， 它 所 做 的 工作 是 对 发 送 给 用 户 的 HITP 啊 应 
包 做 一 些 加 工 。 在 6.1T 和 6.2 节 中 将 会 介绍 默认 编译 进 Nginx 的 官方 
HTTP 过 滤 模 块 ， 从 这 些 模块 的 功能 上 就 可 以 对 比 出 HTTP 过 滤 模 块 与 
HTTP 处 理 模 块 的 不 同 之 处 。 HTTP 过 滤 模 块 不 会 去 访问 第 三 方 服 务 ， 
所 以 第 5 章 中 介绍 的 upstream 和 subrequest 机 制 在 本 章 中 都 不 会 使 用 到 。 


实际 上 ， 在 阅读 完 第 3 章 和 第 4 章 内 容 后 再 来 学 习 本 章 内 容 ， 相 信 
读者 会 发 现 开 发 HITP 过 滤 模 块 是 一 件 非常 答 单 的 事情 。 在 6.4 世 中 ， 
我 们 通过 一 个 简单 的 例子 来 演示 如 何 开 发 HTTP 过 滤 模 块 。 


6.1 过 滤 模 块 的 意义 


HTTP 过 滤 模块 与 普通 HTTP 模 块 的 功能 是 完全 不 同 的 ， 下 面 先 来 
回顾 一 下 普通 的 HTTP 模 块 有 何 种 功能 。 


HTTP 框 染 为 HTTP 请 求 的 处 理 过 程 定 义 了 11 个 阶段 ， 相 关 代 码 如 
下 所 示 : 


typedef enum { 
NGX_HTTP_POST_READ_PHASE = 0, 
NGX_HTTP_SERVER_REWRITE_PHASE， 
NGX_HTTP_FIND_CONFIG_PHASE， 
NGX_HTTP_REWRITE_PHASE， 
NGX_HTTP_POST_REWRITE_PHASE, 
NGX_HTTP_PREACCESS_PHASE， 
NGX_HTTP_ACCESS_PHASE， 
NGX_HTTP_POST_ACCESS_PHASE， 
NGX_HTTP_TRY_FILES_PHASE, 
NGX_HTTP_CONTENT_PHASE， 
NGX_HTTP_LOG_PHASE 

} ngx_http_phases ， 


HTTP 框 架 允 许 普通 的 HTTP 处 理 模块 介入 其 中 的 7 个 阶段 处 理 请 
求 ， 但 是 通常 大 部 分 HTTP 模 块 (官方 模块 或 者 第 三 方 模块 都 只 在 
NGX_HTTP_CONTENT_PHASE 阶 段 处 理 请 求 。 在 这 一 阶段 处 理 请 求 
有 一 个 特点 ， 即 HTTP 模 块 有 两 种 介入 方法 ， 第 一 种 方法 是 ， 任 一 个 
HTTP 模 块 会 对 所 有 的 用 户 请 求 产生 作用 ， 第 二 种 方法 是 ， 只 对 请 求 的 
URI 匹 配 了 nginx.conf 中 某 些 location 表 达 式 下 的 HTTP 模 块 起 作用 。 就 
像 第 3 章 中 定义 的 mytest 模 块 一 样 ， 大 部 分 模块 都 使 用 上 述 的 第 二 种 方 


法 处 理 请 求 ， 这 种 方法 的 特点 是 一 种 请 求 仅 由 一 个 HTTP 模 块 (在 
NGX_HTTP_CONTENT_PHASE 阶 段 ) 处 理 。 如 果 和 希望 多 个 HTTP 模 块 
共同 处 理 一 个 请 求 ， 则 多 半 是 由 subrequest 功 能 来 完成 ， 即 将 原始 请 求 
分 为 多 个 子 请 求 ， 每 个 子 请 求 再 由 一 个 HTTP 模 块 在 
NGX_HTTP_CONTENT_PHASE 阶 段 处 理 。 


然而 ，HTTP 过 小 模 块 则 不 同 于 此 ， 一 个 请 求 可 以 被 任意 个 HTTP 
过 滤 模 块 处 理 。 因 此 ， 普 通 的 HTTP 模 块 更 倾向 于 完成 请 求 的 核心 功 
能 ， 如 static 模 块 负责 静态 文件 的 处 理 。HTTP 过 滤 模 块 则 处 理 一 些 附 
加 的 功能 ， 如 gzip 过 滤 模 块 可 以 把 发 送 给 用 户 的 静态 文件 进行 gzip 压 缩 
处 理 后 再 发 出 去 ，image_filter 这 个 第 三 方 过 滤 模 块 可 以 将 图 片 类 的 静 
态 文件 制作 成 缩 略 图 。 而 且 ， 这 些 过 滤 模 块 的 效果 是 可 以 根据 需要 释 
加 的 ， 比 如 先 由 not_modify 过 滤 模 块 处 理 请 求 中 的 浏览 器 缓存 信息 ， 
再 交 给 range 过 滤 模 块 处 理 HTTP range 协 议 (支持 断 点 续 传 ) ， 然 后 交 
由 gzip 过 滤 模 块 进行 压缩 ， 可 以 看 到 ， 一 个 请 求 经 由 各 HTTP 过 滤 模 块 
流水 线 般 地 依次 进行 处 理 了 。 


HTTP 过 滤 模 块 的 男 一 个 特性 是 ， 在 普通 HTTP 模 块 处 理 请 求 完 
毕 ， 并 调用 ngx_http_send_header 发 送 HTTP 头 部 ， 或 者 调用 
ngx_http_output_filter 发 送 HTTP 包 体 时 ， 才 会 由 这 两 个 方法 依次 调用 
所 有 的 HITP 过 滤 模 块 来 处 理 这 个 请 求 。 因 此 ，HTTP 过 滤 模 块 仅 处 理 


服务 器 发 往 客户 端的 HTTP 响 应 ， 而 不 处 理 客户 端 发 往 服务 器 的 HTTP 
请 求 。 


Nginx 明 确 地 将 HTTP 啊 应 分 为 两 个 部 分 : HITP 头 部 和 HTTP 包 

体 。 因 此 ， 对 应 的 HITP 过 滤 模 块 可 以 选择 性 地 只 处 理 HITP 头 部 或 者 
HTTP 包 体 ， 当 然 也 可 以 二 者 丝 处 理 。 例 如 ，not_modify 过 滤 模 块 只 处 
理 HTTP 头 部 ， 完 全 不 天 心 http 包 体 ， 而 gzip 过 滤 模 块 首 先 会 处 理 HTTP 
头 部 ， 如 检查 浏览 絮 请 求 中 是 否 文 持 gzip 解 压 ， 然 后 检查 啊 应 中 HTTP 
头 部 里 的 Content-Type 是 否 属于 nginx.conf 中 指定 的 gzip 压 缩 类 型 ， 接 着 
才 处 理 HTTP 包 体 ， 针 对 每 一 块 buffer 绥 冲 区 都 进行 gzip 压 缩 ， 这 样 再 
交 给 下 一 个 HTTP 过 滤 模 块 处 理 。 


6.2 过滤 模块 的 调用 顺序 


既然 一 个 请 求 会 被 所 有 的 HTTP 过滤 模块 依次 处 理 ， 那 么 下 面 来 看 
一 下 这 些 HTTP 过 滤 模 块 是 如 何 组 织 到 一 起 的 ， 以 及 它们 的 调用 顺序 是 
如 何 确定 的 。 


6.2.1 过 滤 链 表 是 如 何 构成 的 


在 编译 Nginx 源 代码 时 ， 已 经 定义 了 一 个 由 所 有 HTTP 过 滤 模 块 组 
成 的 单 链表 ， 这 个 单 链表 与 一 般 的 链表 是 不 一 样 的 ， 它 有 男 类 的 风 
格 : 链表 的 每 一 个 元 素 都 是 一 个 独立 的 C 源 代码 文件 ， 而 这 个 C 源 代码 
文件 会 通过 两 个 static 静 态 指针 (分 别 用 于 处理 HTTP 头 部 和 HTTP 包 
体 ) 再 指向 下 一 个 文件 中 的 过 滤 方 法 。 在 HTTP 框 架 中 定义 了 两 个 指 
针 ， 指 向 整个 链表 的 第 一 个 元 素 ， 也 就 是 第 一 个 处 理 HTTP 头 部 、 
HTTP 包 体 的 方法 。 


这 两 个 处 理 HTTP 头 部 和 HTTP 包 体 的 方法 是 什么 样 的 呢 ? HTTP 框 
染 进 行 了 如 下 定义 : 


typedef ngx_int_t (*ngx_http_output_ header_filter_pt) 
(ngx_http_request_t *r); 

typedef ngx_int_t (*ngx_http_output_body_filter_pt) 
(ngx_http_request_t *r, ngx_chain_t *chain); 


如 上 所 示 ，ngx_http_output_header _filter_pt 是 每 个 过 滤 模 块 处 理 
HTTP 头 部 的 方法 原型 ， 它 仅 接收 1 个 参数 r， 也 就 是 当前 的 请 求 ， 其 返 
回 值 一 般 是 与 3.6.1 节 中 介绍 的 返回 码 通 用 的 ， 如 NGX_ERROR 表 示 失 
败 ， 而 NGX_OK 表 示 成 功 。 


ngx_http_output_body_filter_pt 是 每 个 过 小 模块 处 理 HTTP 包 体 的 方 
法 原型 ， 它 接收 两 个 参数 一 r 和 chain， 其 中 r 是 当前 的 请 求 ，chain 是 要 
发 送 的 HTTP 包 体 ， 其 返回 值 与 ngx_http_output_header_filter_pt 相 同 。 


所 有 的 HTTP 过 滤 模 块 需要 实现 这 两 个 方法 (或 者 仅 实现 其 中 的 一 
个 也 是 可 以 的 ) 。 因 此 ， 这 个 单 向 链表 是 围绕 着 每 个 文件 (也 就 是 
HTTP 过 滤 模 块 ) 中 的 这 两 个 处 理 方 法 来 建立 的 ， 也 就 是 说 ， 链 表 中 的 
元 素 实际 上 就 是 处 理 方法 。 


先 来 看 一 下 HTTP 框 架 中 定义 的 链表 入 口 : 


extern ngx_http_output_header_filter_pt ngx_http_top_header_filter， 
extern ngx_http_output_body_filter_pt ngx_http_top_body_filter,; 


当 执行 ngx_http_send_header 发 送 HTTP 头 部 时 ， 就 从 
ngx_http_top_header filter 指 针 开 始 遍历 所 有 的 HITP 头 部 过 滤 模 块 ， 而 
在 执行 ngx_http_output_filter 发 送 HTTP 包 体 时 ， 就 从 
ngx_http_top_body_ filter 指针 开始 遍历 所 有 的 HITP 包 体 过 减 模块 。 下 面 
来 看 一 下 在 Nginx 源 代码 中 是 如 何 做 的 : 


ngx_int_t 
ngx_http_send header (ngx_http_request_t *r) 


{ 
if (r->err_status) { 
r->headers_out,.status = r->err_status; 
r->headers_out.status_line.len = 0; 
return ngx_http_top_header_filter(r); 
} 


在 发 送 HTTP 头 部 时 ， 从 ngx_http_top_header_filter 指 针 指 向 的 过 滤 
模块 开始 执行 。 而 发 送 HTTP 包 体 时 都 是 调用 ngx_http_output_filter 方 
法 ， 如 下 所 示 : 


ngx_int_t 
ngx_http_output_filter(ngx_http_request_t *r, ngx_chain_t *in) 
{ 

ngx_int_t rec; 

ngx_connection t *c,; 

Cc = r->connection,; 

rc = ngx_http_top_body_filter(r, in); 

if (rc == NGX_ERROR) { 

/* NGX_ERROR 可 能 由 任何 过 滤 模 块 返 蕊 


c->error = 1; 


return rc; 


遍历 访问 所 有 的 HTTP 过 滤 模 块 时 ， 这 个 单 链表 中 的 元 素 是 起 么 用 
next 指 针 连 接 起 来 的 呢 ? 很 简单 ， 每 个 HTTP 过 滤 模 块 在 初始 化 时 ， 会 
先 找 到 链表 的 首 元 素 ngx_http_top_header _filter 指 针 和 
ngx_http_top_body_filter 指 针 ， 再 使 用 static 静 态 类 型 的 
ngx_http_next_header_filter 和 ngx_http_next_body_filter 指 针 将 自己 插入 
到 链表 的 首部 ， 这 样 就 行 了 。 下 面 来 看 一 下 在 每 个 过 小 模 块 中 
ngx_http_next_header_filter 和 ngx_http_next_body_filter 指 针 的 定义 : 


static ngx_http_output_header_filter_pt ngx_http_next_header filter; 
static ngx_http_output_body_filter_pt ngx_http_next_body_filter; 


注意 ，ngx_http_next_header filter 和 ngx_http_next_body_filter 都 必 
须 是 static 静 态 变量 ， 为 什么 呢 ? 因为 static 类 型 可 以 让 上 面 两 个 变量 仅 
在 当前 文件 中 生效 ， 这 就 允许 所 有 的 HITP 过 滤 模 块 都 有 各 上 自 的 
ngx_http_next_header_filter 和 ngx_http_next_body_filter 指 针 。 这 样 ， 在 
每 个 HTTP 过 滤 模 块 初始 化 时 ， 就 可 以 用 上 面 这 两 个 指针 指向 下 一 个 
HTTP 过 滤 模 块 了 。 例 如 ， 可 以 像 下 列 代码 一 样 将 当前 HTTP 过 滤 模 块 
的 处 理 方法 添加 到 链表 首部 。 


ngx_http_next_header_filter = ngx_http_top_header filter; 
ngx_http_top_header_filter = ngx_http_myfilter_header_filter; 
ngx_http_next_body_filter = ngx_http_top_body_filter,; 
ngx_http_top_body_filter = ngx_http_myfilter_body_filter,; 


这 样 ， 在 初始 化 到 本 模块 时 ， 自 定义 的 
ngx_http_myfilter_header_filter 与 ngx_http_myfilter_body_filter 方 法 就 暂 
时 加 入 到 了 链表 的 首部 ， 而 且 本 模块 所 在 文件 中 static 类 型 的 
ngx_http_next_header_filter 指 针 和 ngx_http_next_body_filter 指 针 也 指向 
了 链表 中 原来 的 首部 。 在 实际 使 用 中 ， 如 果 需 要 调用 下 一 个 HITP 过 滤 
模块 ， 只 需要 调用 ngx_http_next_header filter(r) 或 者 
ngx_http_next_body_filter(r,chain) 就 可 以 了 。 


6.2.2 ”过 滤 链 表 的 顺序 


HTTP 过 滤 模 块 之 间 的 调用 顺序 是 非常 重要 的 。 如 有 果 两 个 HITP 过 
滤 模 块 按照 相反 的 顺序 执行 ， 完 全 可 能 生成 两 个 不 同 的 HTTP 员 应 包 。 
例如 ， 如 有 果 现 在 有 一 个 图 片 缩 略图 过 滤 模 块 ， 还 有 一 个 图 片 裁 瘟 过 滤 
模块 ， 当 返回 一 张 图 片 给 用 户 时 ， 这 两 个 模块 的 执行 顺序 不 同 的 话 就 
会 导致 用 户 接收 到 不 一 样 的 图 片 。 


在 上 文中 提 到 过 ，Nginx 在 编译 过 程 中 束 会 决定 HTTP 过 滤 模 块 的 
顺序 。 这 件 事情 到 底 是 怎样 发 生 的 呢 ? 这 其 实 与 3.3 节 中 所 说 的 普通 
HTTP 模 块 的 顺序 是 一 样 的 ， 也 是 由 configure 生 成 的 ngx_modules 数 组 中 
各 模块 的 顺序 决定 的 。 


由 于 每 个 HTTP 过 滤 模 块 的 初始 化 方法 都 会 把 目 己 加 入 到 单 链表 的 
首部 ， 所 以 ， 什 么 时 候 、 以 何 种 顺序 调用 这 些 HTTP 过 滤 模 块 的 初始 化 
方法 ， 将 会 决定 这 些 HTTP 过 滤 模 块 在 单 链表 中 的 位 置 。 


什么 时 候 开 始 调用 各 个 HTTP 模 块 的 初始 化 方法 呢 ? 这 主要 取决 于 
我 们 把 类 似 ngx_http_myfilter_init 这 样 的 初始 化 方法 放 到 
ngx_http_module i 结构 体 的 哪个 回调 方法 成 员 中 。 例 如 ， 大 多 数 官方 
HTTP 过 滤 模 块 都 会 把 初始 化 方法 放 到 postconfiguration 指 针 中 ， 那 么 它 
就 会 在 图 4-1 的 第 6 步 将 当前 模块 加 入 到 过 滤 链 表 中 。 不 建议 把 初始 化 方 
法 放 到 ngx_http_module t 的 其 他 成 员 中 ， 那 样 会 导致 HITP 过 滤 模 块 的 
顺序 不 可 控 。 


初始 化 时 的 顺序 又 是 如 何 决 定 的 呢 ? 首先 回顾 一 下 第 1 章 的 相关 内 
容 ， 在 1.7 广 中 ， 介 绍 了 configure 命 令 生 成 的 ngx_modules.c 文 件 ， 这 个 
文件 中 的 ngx_modules 数 组 会 保存 所 有 的 Nginx 模 块 ， 包 括 HTTP 普 通 模 
块 和 HTTP 过 滤 模 块 ， 而 初始 化 Nginx 模 块 的 顺序 就 是 ngx_modules 数 组 
成 员 的 顺序 。 因 此 ， 只 需要 查看 configure 命 令 生 成 的 ngx_modules.c 文 
件 就 可 以 知道 所 有 HTTP 过 滤 模 块 的 顺序 了 。 


由 此 可 知 ，HTTP 过 小 模 块 的 顺序 是 由 configure 命 令 生 成 的 。 当 
然 ， 如 果 用 户 对 configure 命 令 生 成 的 模块 顺序 不 满意 ， 完 全 可 以 在 
configure 命 令 执行 后 、make 编 译 命令 执行 前 修改 ngx_modules.c 文 件 的 
内 容 ， 对 ngx_modules 数 组 中 的 成 员 进行 顺序 上 的 调整 。 


@ j 意 “对 于 HTTP 过 滤 模 块 来 说 ， 在 ngx_modules 数 组 中 的 位 置 
越 靠 后， 在 实际 执行 请 求 时 就 越 优先 执行 。 因 为 在 初始 化 HTTP 过 滤 模 
块 时 ， 每 一 个 htp 过 滤 模 块 都 是 将 自己 插入 到 整个 单 链表 的 首部 的 。 


configure 执 行 时 是 怎样 确定 Nginx 模 块 间 的 顺序 的 呢 ? 当 我 们 下 载 
官方 提供 的 Nginx 源 代码 包 时 ， 官 方 提供 的 HTTP 过 滤 模 块 顺序 已 经 写 
在 auto 目 录 下 的 modules 脚 本 中 了 “。 图 6-1 描 述 了 这 个 顺序 。 


如 果 在 执行 configure 命 令 时 使 用 --add-module 选 项 新 加 入 第 三 方 的 
HTTP 过 滤 模 块 ， 那 么 第 三 方 过 滤 模 块 会 处 于 ngx_modules 数 组 中 的 哪 
个 位 置 呢 ? 答案 也 可 以 在 图 6-1 中 找到 。 


如 图 6-1 所 示 ， 在 执行 configure 命 令 时 仅 使 用 --add-module 参 数 添 加 
了 第 三 方 HTTP 过 滤 模 块 。 这 里 没有 把 默认 未 编译 进 Nginx 的 官方 HITP 
过 滤 模 块 考虑 进去 。 这 样 ， 在 configure 执 行 完 毕 后 ，Nginx 各 HTTP 过 滤 
模块 的 执行 顺序 就 确定 了 。 默 认 HTTP 过 滤 模 块 间 的 顺序 必须 如 图 6-1 所 
示 ， 因 为 它们 是 “ 写 死 "在 auto/modules 脚 本 中 的 。 读 者 可 以 通过 阅读 这 
个 modules 脚 本 的 源 代码 了 解 Nginx 是 如 何 根据 各 官方 过 滤 模 块 功能 的 
不 同 来 决定 它们 的 顺序 的 。 对 于 图 6-1 中 所 列 的 这 些 过 滤 模 块 ， 将 在 下 
面 进 行 简 单 的 介绍 。 


ngx_http _ssi_ llermodule) 


(op _ postpone _ Fler medale) 


(oe _http gzip _filter_ no 


Ce _http_range_header _ for node) 


| 


(re _chunked na hy 


(oe _header_filter _ note) 


(oe _http _write_filter _ maule) 


| 


(ee _http _not_modified _filter _modul 


be _http _range_body_filter_ no 


GC _http_copy_ Fler nodule) 


(oe _http _ headers _filter_mod ou) 


(第 至 :7 订 HTp 过 让 模 


GB 


(oe _http _userid her_module) 


人 _http _charset_filter_module 


图 6-1 默认 即 编译 进 Nginx 的 官方 HTTP 过 滤 模 块 与 第 三 方 HTTP 过 滤 模 
块 间 的 顺序 


6.2.3 ”官方 默认 HTTP 过 滤 模 块 的 功能 简介 


本 市 
1) ， 通 过 对 它们 的 了 解 ， 
的 排序 依据 是 什么 。 如 果 用 户 对 configure 命 令 执行 
就 可 以 正确 地 修改 这 些 过 滤 模 块 间 的 顺序 。 


介绍 默认 即 编译 进 Nginx 的 HTTP 过 滤 模 块 的 功能 ( 见 表 6- 
读者 就 会 明白 图 6-1 列 出 的 HTTP 过 滤 模 块 间 
后 的 模块 间 顺 序 不 满 


局 ) 


表 6-1 默认 即 编译 


默认 即 编译 进 Nginx 的 HTTP 过 滤 模 块 


进 Nginx 的 HTTP 过 滤 模 块 


功 能 


ngx_http_ not_ modified filter_ module 


ngx http_range body filter module 


ngx_http copy _ filter_ module 


ngx_http_headers filter module 


ngx_http_userid filter module 


ngx_http_charset filter module 


ngx_ http_ssi filter _ module 


ngx_http_postpone filter_ module 


ngx_http_gzip_filter_ module 


ngx_http_range header filter module 


ngx_http_chunked filter_ module 


ngx_http_header filter_ module 


ngx_http_ write filter module 


仅 对 HTTP 头 部 做 处 理 。 在 返回 200 成 功 时 ,根据 请 求 中 If-Modified- 
Since 或 者 IEUnmodified-Since 头 部 取得 浏览 器 缓存 文件 的 时 间 ， 再 分 析 
返回 用 户 文件 的 最 后 修改 时 间 ， 以 此 决定 是 否 直 接 发 送 304 Not Modified 


响应 给 用 户 
处 理 请 求 中 的 Range 信息 ， 根 据 Range 中 的 要 求 返 回 文件 的 一 部 分 给 
用 户 


仅 对 HTIP 包 体 做 处 理 。 将 用 户 发 送 的 ngx_chain t 结 构 的 HTIP 包 
体 复制 到 新 的 ngx_chain t 结 构 中 (都 是 各 种 指针 的 复制 ,不 包括 实际 
HTTP 响应 内 容 )， 后 续 的 HTTP 过 滤 模 块 处 理 的 ngx_chain t 类 型 的 成 员 
部 是 ngx_http_copy_filter_module 模块 处 理 后 的 变量 

仅 对 HTTP 头 部 做 处 理 。 即 许 通过 修改 nginx.conf 配置 文件 ， 在 返回 
给 用 户 的 响应 中 添加 任意 的 HTTP 头 部 

仅 对 HTTP 头 部 做 处 理 。 这 就 是 执行 configure 命令 时 提 到 的 http_ 
userid_module 模块 ， 它 基于 cookie 提供 了 简单 的 认证 管理 功能 

可 以 将 文本 类 型 返回 给 用 户 的 响应 包 ， 按 照 nginx.conf 中 的 配置 重新 
进行 编码 ， 再 返回 给 用 户 

支持 SSI ( Server Side Include， 
到 网 页 中 并 返回 给 用 户 

仅 对 HTTP 包 体 做 处 理 。5.5.2 节 详 细 介 绍 过 该 过 滤 模 块 。 它 仪 应 用 于 
subrequest 产后 的 子 请 求 。 它 使 得 多 个 子 请 求 同 时 间 客 户 端 发 送 响 应 时 能 
够 有 序 ， 所 谓 的 “有 序 ” 是 指 按照 构造 子 请 求 的 顺序 发 送 响 应 

对 特定 的 HTTP 响应 包 体 (如 网 页 或 者 文本 文件 ) 进行 gzip 压缩 ， 再 
把 压缩 后 的 内 容 返 回 给 用 户 

支持 range 协议 

支持 chunk 编码 

仅 对 HTTP 头 部 做 处 理 。 该 过 滤 模 块 将 会 把 r>headers out 结构 体 
中 的 成 员 序 列 化 为 返回 给 用 户 的 HTTP 响应 字符 流 ， 包 括 响应 行 (如 
HTTP/1.1 200 OK) 和 啊 应 头 部 ， 并 通过 调用 ngx http_ write_ filter_ 
module 过 滤 模 块 中 的 过 滤 方 法 直接 将 HTTP 包头 发 送 到 客户 端 

仅 对 HTTP 包 体 做 处 理 。 该 模块 负责 向 客户 端 发 送 HTTP 响应 


服务 器 器 嵌 和 人 ) 功能 ， 将 文件 内 容 包含 


从 表 6-1 中 可 以 了 解 到 这 些 默认 的 HTTP 过 滤 模 块 为 什么 要 以 图 6-1 
的 顺序 排列 ， 同 样 可 以 弄 清楚 第 三 方 过 滤 模 块 为 何 要 在 
ngx_http_headers_filter_module 模 块 之 后 、ngx_http_userid_filter_module 
模块 之 前 。 


在 开发 HTTP 过 滤 模 块 时 ， 如 果 对 configure 执 行 后 的 过 滤 模 块 顺序 
不 满意 ， 那 么 在 修改 ngx_modules.c 文 件 时 先 要 对 照 表 6-1 看 一 下 每 个 模 


块 的 功能 是 否 符合 它 的 位 置 。 


6.3 ” HTTP 过 小 模块 的 开发 步 又 


HTTP 过 滤 模 块 的 开发 步骤 与 第 3 章 中 所 述 的 普通 HTTP 模 块 的 开发 
步骤 基本 一 致 ， 这 里 再 简要 地 概括 一 下 ， 即 如 下 8 个 步骤 : 


1) 确定 源 代 码 文件 名 称 。 通 常 ，HTTP 过 滤 模 块 的 功能 都 比较 单 
一 ， 因 此 ， 一 般 1 个 C 源 文件 就 可 以 实现 1 个 HITP 过 滤 模 块 。 由 于 需要 
将 源 文件 加 入 到 Makefile 中 ， 因 此 这 时 就 要 确定 好 源 文件 名 称 。 当 
然 ， 用 多 个 C 源 文件 甚至 C++ 源 文件 实现 1 个 HTTP 过 滤 模 块 也 是 可 以 
的 ， 可 参考 3.3 节 和 3.9 节 ， 这 里 不 再 长 述 。 


2) 在 源 代码 所 在 目录 创建 config 脚 本 文件 ， 当 执行 configure 时 将 
该 目录 添加 进去 。config 文 件 的 编写 方法 与 3.3.1 节 中 开发 普通 HTTP 模 
块 时 介绍 的 编写 方法 基本 一 致 ， 唯 一 需要 改变 的 是 ， 把 
HTTP_MODULES 变 量 改 为 HITP_FILTER_MODULES 变 量 ， 这 样 才 会 
把 我 们 的 模块 作为 HTTP 过 滤 模 块 ， 并 把 它 放 置 到 正确 的 位 置 (图 6-1 
所 示 的 第 三 方 过 滤 模 块 位 置 ) 上 


在 执行 configure 命 令 时 ， 其 编译 方法 与 3.3.2 节 中 介绍 的 是 一 样 
的 。 在 执行 configure--add-module=PATH 时 ，PATH 就 是 HITTP 过 滤 模 块 
源 文件 所 在 的 路 径 。 当 多 个 源 代码 文件 实现 1 个 HITP 过 滤 模 块 时 ， 需 
在 NGX_ADDON_SRCS 变 量 中 添加 其 他 源 代 码 文件 。 


3) 定义 过 滤 模 块 。 实 例 化 ngx_module t 类 型 的 模块 结构 ， 这 与 3.4 
节 介绍 的 内 容 类似 ， 同 时 可 以 参考 3.5 节 中 的 例子 。 因 为 HTTP 过 滤 模 
块 也 是 HTTP 模 块 ， J 其 中 的 type 成 员 
也 是 NGX_HTTP_MODULE 。 步骤 与 定义 普通 的 HITP 模 块 是 相同 
的 。 


4) 处 理 感 兴趣 的 配置 项 。 依 照 第 4 章 中 介绍 的 方法 ， 可 通过 设置 
ngx_module _t 结 构 中 的 ngx_command t 数 组 来 处 理 感 兴趣 的 配置 项 。 


5) 实现 初始 化 方法 。 初 始 化 方法 就 是 把 本 模块 中 处 理 HITP 头 部 
的 ngx_http_output_header_filter_pt 方 法 与 处 理 HTTP 包 体 的 
ngx_http_output_body_filter_pt 方 法 插入 到 过 滤 模 块 链 表 的 首部 ， 参 见 
6.2.1 玫 中 的 例子 。 


6) 实现 处 理 HITP 头 部 的 方法 。 实 现 
ngx_http_output_header_filter_pt 原 型 的 方法 ， 用 于 处 理 HTTP 头 部 ， 如 
下 所 示 : 


typedef ngx_int_t (*ngx_http_output_header_filter_pt) (ngx_http_request_t *r); 


一 定 要 在 模块 初始 化 方法 中 将 其 添加 到 过 滤 模 块 链表 中 。 


7) 实现 处 理 HTTP 包 体 的 方法 。 实 现 
ngx_http_output_body_filter_pt 原 型 的 方法 ， 用 于 处 理 HTTP 包 体 ， 如 下 


所 示 : 


typedef ngx_int_t (*ngx_http_output_body_filter_pt) (ngx_http_request_t *r, 
ngx_chain_t *chain); 


一 定 要 在 模块 初始 化 方法 中 将 其 添加 到 过 滤 模 块 链表 中 。 


8) 编译 安装 后 ， 修 改 nginx.conf 文 件 并 启动 自 定义 过 滤 模 块 。 通 
常 ， 出 于 灵活 性 考虑 ， 在 配置 文件 中 都 会 有 配置 项 决定 是 否 启 动 模 
块 。 因 此 ， 执 行 make 编 译 以 及 make install 安装 后 ， 再 修改 nginx.conf 文 
件 中 的 配置 项 ， 目 定义 过 滤 模 块 的 功能 。 


6.4 _ HTTP 过 滤 模 块 的 商 单 例子 


本 市 通过 一 个 简单 的 例子 来 说 明 如 何 开 发 HTTP 过 滤 模 块 。 场 景 是 
这 样 的 ， 用 户 的 请 求 由 static 静 仿 文 件 模 块 进行 了 处 理 ， 它 会 根据 URI 返 
回 人 磁盘 中 的 文件 给 用 户 。 而 我 们 开发 的 过 滤 模 块 束 会 在 运 回 给 用 户 的 
响应 包 体 前 加 一 段 字符 串 : "[my filter prefix]"。 需 要 实现 的 功能 就 是 这 
么 简单 ， 当 然 ， 可 以 在 配置 文件 中 决定 是 人 否 开局 此 功能 。 


图 6-2 簿 单 地 描绘 了 处 理 HTTP 头 部 的 方法 将 会 执行 的 操作 ， 而 图 6- 
3 则 是 处 理 HTTP 包 体 的 方法 将 会 执行 的 操作 。 


[返回 非 200] 


检查 Content -Type 是 否 是 文 本 类 型 


[ 包 体 的 类 型 是 文本 文件 ] 


设置 HTTP 上 下 文 表示 当前 请 求 的 响应 包 体 时 
要 加 前 绥 


执行 下 一 个 过 滤 模 块 的 HTTP 
头 部 过 滤 函 数 


图 6-2 过滤 模 块 例子 中 ，HTTP 头 部 处 理 方法 的 执行 活动 图 


与 图 6-2 相 天 的 代码 可 参见 6.4.5 条 。 


检查 HTTP 上 下 文中 是 否 表示 要 加 前 绥 


[上 下 文中 显示 需要 处 理 的 包 体 ] ss 
[不 需要 处 理 包 体 ] 


在 当前 待 发 送 的 HTTP 包 体 前 添加 前 绥 


执行 下 一 个 过 滤 模 块 的 HTTP 包 体 过 滤 方 法 


图 6-3 “过滤 模块 例子 中 ，HTTP 包 体 处 理 方法 的 执行 活动 图 
与 图 6-3 相 关 的 代码 可 参见 6.4.6 节 。 


由 于 HTTP 过 滤 模 块 也 是 一 种 HTTP 模 块 ， 所 以 大 家 会 发 现 本 章 
myfilter 过 滤 模 块 的 代码 与 第 3 章 介 绍 的 例子 中 的 代码 很 相似 。 


6.4.1 如 何 编写 config 文 件 


可 以 仅 用 1 个 源 文件 实现 上 述 HTTP 过 滤 模 块 ， 源 文件 名 为 
ngx_http_myfilter_module.c。 在 该 文件 所 在 目录 中 添加 config 文 件 ， 其 
内 容 如 下 : 


ngx_addon_name=ngx_http_myfilter_module 
HTTP_FILTER_MODULES="$HTTP_FILTER_MODULES ngx_http_myfilter_module" 
NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_myfilter_module.c" 

将 模块 名 添加 到 HTTP_FILTER_MODULES 变 量 后 ，auto/modules 
脚本 就 会 按照 6.2.2 节 中 定义 的 顺序 那样 ， 将 ngx_http_myfilter_module 过 
滤 模 块 添加 到 ngx_modules 数 组 的 合适 位 置 上 。 其 中 ， 
NGX_ADDON_SRCS 定 义 的 是 竺 编译 的 C 源 文件 。 


6.4.2 ”配置 项 和 上 下 文 


目 先 布 望 在 nginx.conf 中 有 一 个 控制 当前 HTTP 过 滤 模 块 是 否 生效 的 
配置 项 ， 它 的 参数 值 为 on 或 者 off， 分 别 表示 开 局 或 者 关闭。 因此 ， 按 
照 第 4 章 介 绍 的 用 法 ， 需 要 建立 ngx_http_myfilter_conf_t 结 构 体 来 存储 配 
置 项 ， 其 中 使 用 ngx_flag_t 类 型 的 enable 变 量 来 存储 这 个 参数 值 ， 如 下 
Mm 


typedef struct { 
ngx_flag_t enable,; 
} ngx_http_myfilter_conf_t; 


同样 ， 下 面 实 现 的 ngx_http_myfilter_create_conf 用 于 分 配 存储 配置 
项 的 结构 体 ngx_http_myfilter_conf t: 


static void* ngx_http_myfilter_create conf(ngx_conf_t *cf) 


ngx_http_myfilter_conf_t  *mycf， 
// 创建 存储 配置 项 的 结构 体 


mycf = (ngx_http_myfilter_conf_t *)ngx_pcalloc(cf->pool, 
sizeof (ngx_http_myfilter_conf_t)); 
If (mycf == NULL) { 
return NULL; 


} 
// ngx_flat_t 类 型 的 变量 。 如 果 使 用 预 设 函 数 


ngx_conf_set_flag_slot 解 析 配 置 项 参数 ， 那 么 必须 初始 化 为 


NGX_CONF_UNSET 
mycf->enable= NGX_CONF_UNSET ， 
return mycf， 


吏 像 gzip 等 其 他 HTTP 过 滤 模 块 的 配置 项 一 样 ， 我 们 往往 会 允许 配 
置 项 不 只 出 现在 location{.…} 配 置 块 中 ， 还 可 以 出 现在 server{.…} 或 者 
http{.….} 配 置 块 中 ， 因 此 ， 还 需要 实现 一 个 配置 项 值 的 合并 方法 一 一 
ngx_http_myfilter_merge_conf， 代 码 如 下 所 示 : 


static char * 
ngx_http_myfilter_merge conf(ngx_conf_t *cf, void *parent, void *child) 


ngx_http_myfilter_conf_t *prev = (ngx_http_myfilter_conf_t *)parent,; 
ngx_http_myfilter_conf_t *conf = (ngx_http_myfilter_conf_t *)child; 
// 合并 


ngx_flat_t 类 型 的 配置 项 


enable 

ngx_conf_merge_value(conf->enable, prev->enable, 0); 
return NGX_CONF_OK; 

} 


根据 6.4.3 节 中 介绍 的 配置 项 名 称 可 知 ， 在 nginx.conf 配 置 文件 中 需 
要 有 “add_prefix on;” 字 样 的 配置 项 。 


再 建立 一 个 HITP 上 下 文 结 构 体 ngx_http_myfilter_ctx_t， 其 中 包括 
add_prefix 整 型 成 员 ， 在 处 理 HTTP 头 部 时 用 这 个 add_prefix 表 示 在 处 理 
HTTP 包 体 时 是 否 添 加 前 级 。 


typedef struct { 
ngx_int_t add_prefix; 
} ngx_http_myfilter_ctx_t; 


当 add_prefix 为 0 时 ， 表 示 不 需要 在 返回 的 包 体 前 加 前 级 ; 当 
add_prefix 为 1 时 ， 表 示 应 当 在 包 体 前 加 前 绥 ; 当 add_prefix 为 2 时 ， 表 示 
已 经 添加 过 前 级 了 。 为 什么 add_prefix 有 3 个 值 呢 ? 因 为 HTTP 头 部 处 理 
方法 在 1 个 请 求 中 只 会 被 调用 1 次 ， 但 包 体 处 理 方 法 在 1 个 请 求 中 是 有 可 
能 被 多 次 调用 的 ， 而 实际 上 我 们 只 和 希望 在 包头 加 1 次 前 缀 ， 因 此 
add_prefix 制 定 了 3 个 值 。 


6.4.3 定义 HTTP 过 滤 模 块 


定义 ngx_module_t 模 块 前 ， 需 要 先 定义 好 它 的 两 个 关键 成 员 : 
ngx_command_t 类 型 的 commands 数 组 和 ngx_http_module_t 类 型 的 ctx 成 


O 〇 


pil 


下 面 定 义 了 ngx_http_myfilter_commands 数 组 ， 它 会 处 理 add_prefix 
配置 项 ， 将 配置 项 参数 解析 到 ngx_http_myfilter_conf tt 上下文 结 构 体 的 
enable 成 员 中 。 


static ngx_command t ngx_http_myfilter_commands[] = { 
{ ngx_string("add_prefix"), 


NGX_HTTP_MAIN_CONF |NGX_HTTP_SRV_CONF |NGX_HTTP_LOC_CONF |NGX_HTTP_LMT_CONF |NGX_CONF_ 
FLAG, 
ngx_conf_set_flag_slot, 
NGX_HTTP_LOC_CONF_OFFSET, 
offsetof(ngx_http_myfilter_conf_t, enable), 
NULL }, 
ngx_null_command 


在 定义 ngx_http_module_t 类 型 的 ngx_http_myfilter_module_ctx 时 ， 
需要 将 6.4.2 市 中 定义 的 ngx_http_myfilter_create_conf 回 调 方 法 放 到 
create_loc_conf 成 员 中 ， 而 ngx_http_myfilter_merge_conf 回 调 方法 则 要 
放 到 merge_loc_conf 成 员 中 。 另 外 ， 在 6.4.4 节 中 定义 的 
ngx_http_myfilter_init 模 块 初始 化 方法 也 要 放 到 postconfiguration 成 员 
中 ， 表 示 当 读 取 完 所 有 的 配置 项 后 就 会 回调 ngx_http_myfilter_init 方 
法 ， 代 码 如 下 所 示 : 


static ngx_http_module t ngx_http myfilter module ctx = { 


NULL, /* preconfiguration 方 法 
A 

ngx_http_myfilter_init, /* postconfiguration 方 法 
A 

NULL, /* create_main_conf 方 法 
*/ 

NULL, /* init_main_conf 方 法 
*/ 


NULL, /* create_srv_conf 方 法 


i 
NULL, /* merge_srv_conf 方 法 


< 


ngx_http_myfilter_create_conf,/* create_loc_conf 方 法 


“人 
ngx_http_myfilter_merge_conf /* merge_loc_conf 方 法 


«7/ 
}; 
有 了 ngx_command_t 类 型 的 commands 数 组 和 ngx_http_module_t 类 
型 的 ctx 成 员 后 ， 下 面 就 可 以 定义 ngx_http_myfilter_module 过 小 模块 


ngx_module t ngx_http myfilter module = { 
NGX_MODULE_V1, 


&ngx_http_myfilter_module_ctx, /* module context */ 
ngx_http_myfilter_commands, /* module directives */ 
NGX_HTTP_MODULE， /* module type */ 

NULL, /* init master */ 

NULL, /* init module */ 

NULL, /* init process */ 

NULL, /* init thread */ 

NULL, /* exit thread */ 

NULL, /* exit process */ 

NULL, /* exit master */ 


NGX_MODULE_V1_ PADDING 
}; 


它 的 类 型 仍然 是 NGX_HTTP_ MODULE 。 


6.4.4 初始 化 HTTP 过 滤 模 块 


在 定义 ngx_http_myfilter_init 方 法 时 ， 首 移 需 要 定义 静态 指针 
ngx_http_next_header_filter， 用 于 指 癌 下 一 个 过 滤 模 块 的 HTTP 头 部 处 理 


方法 ， 然 后 要 定义 静态 指针 ngx_http_next_body_filter， 用 于 指向 下 一 个 
过 滤 模 块 的 HTTP 包 体 处 理 方法 ， 代 码 如 下 所 示 。 


static ngx_http_output_header_filter_pt ngx_http_next_header filter; 
static ngx_http_output_body_filter_pt ngx_http_next_body_filter; 
static ngx_int_t ngx_http_myfilter_init(ngx_conf_t *cf) 


// 插入 到 头 部 处 理 方法 链表 的 首部 


ngx_http_next_header_filter = ngx_http_top_header_filter; 
ngx_http_top_header_filter = ngx_http_myfilter_header_filter; 
// 插入 到 包 体 处 理 方法 链表 的 首部 


ngx_http_next_body_filter = ngx_http_top_body_filter,; 
ngx_http_top_body_filter = ngx_http_myfilter_body_filter,; 
return NGX_OK， 


6.4.5 ”处理 请 求 中 的 HTTP 头 部 


我 们 需要 把 在 HITP 响 应 包 体 前 加 的 字符 串 前 绥 便 编码 为 
filter_prefix 变 量 ， 如 下 所 示 。 


static ngx_str_t filter_prefix = ngx_string("[my filter prefix]"); 


根据 图 6-2 中 摘 述 的 处 理 流程 ，ngx_http_myfilter_header filter 回 调 
方法 的 实现 应 如 下 所 示 。 


static ngx_int_t 
ngx_http_myfilter_header_filter(ngx_http_request_t *r) 


ngx_http_myfilter_ctx_t *ctx; 
ngx_http_myfilter_conf_t *conf,; 
/* 如 果 不 是 返回 成 功 ， 那 么 这 时 是 不 需要 理会 是 否 加 前 缀 的 ， 直 接 交 由 下 一 个 过 滤 模 块 处 理 响 应 码 非 


200 的 情况 


*/ 


If (r->headers out,.status != NGX_HTTP_OK) { 
return ngx_http_next_header_filter(r); 


} 
// 获取 
HTTP 上 下 文 


ctx = ngx_http_get module ctx(r, ngx_http_ myfilter_module); 


if (ctx) { 


/* 该 请 求 的 上 下 文 已 经 存在 ， 


这 说 明 


ngx_http_myfilter_header_filter 


1 次 ， 直 接 交 由 下 一 个 过 滤 模 块 处 理 


已 经 被 调 


*/ 


return ngx_http_next_header_filter(r); 


} 
// 获取 存储 配置 项 的 


ngx_http_myfilter_conf_t 结 构 体 


conf = ngx_http_get_module_Joc_conf(r， 


/* 如 果 


enable 成 员 为 


9， 也 就 是 配置 文件 中 没有 配 


add_prefix 配 置 项 ， 或 者 


add_prefix 配 置 项 的 参数 值 是 


off， 那 么 这 时 直接 交 


*/ 


if (conf->enable == 0) { 


下 一 个 过 滤 模 块 处 理 


ngx_http_myfilter_module); 


return ngx_http_next_header_filter(r); 


} 
// 构造 


HTTP 上 下 文 结构 体 


ngx_http_myfilter_ctx_t 
ctx = ngx_pcalloc(r->pool, 


if (ctx == NULL) 


return NGX_ERROR; 


} 
// add_prefix 为 


0 表示 不 加 前 级 


ctx->add_prefix = 


{ 


9; 


// 将 构造 的 上 下 文 设 


到 当前 请 求 中 


sizeof(ngx_http_myfilter_ctx_t)); 


ngx_http_set_ctx(r, ctx, ngx_http_myfilter_module); 


// myfilter 过 滤 模 二 


只 处 理 


Content -Type 是 


text/plain” 类 型 的 


HTTP 响 应 


if (r->headers out.content_type.len >= sizeof("text/plain") - 1 
&& Ngx_strncasecmp(r->headers_ out.content_ type.data, (u_char *) 
"text/plain",sizeof("text/plain") - 1) == 0) 


// 设置 为 


1 表示 需要 在 


HTTP 包 体 前 加 入 前 绥 


ctx->add_prefix = 1; 


/* 当 处 理 模 块 已 经 在 


Content -Length 中 写 入 了 


HTTP 包 体 的 长 度 时 ， 


| 


Content -Lengtha 


*/ 


于 我 们 加 入 了 前 组 字符 串 ， 所 以 需要 把 这 个 字符 串 的 长 度 也 加 入 到 


if (r->headers_ out.content_ length n > 0) 
r->headers_out.content_length_n += filter_prefix.1len; 


} 
// 交 由 下 一 个 过 滤 模 块 继续 处 理 


return ngx_http_next_header_filter(r); 


注意 ， 除 非 出 现 了 严重 的 错误 ， 一 般 情况 下 都 需 


滤 模 块 继续 处 理 。 
回 NGX_ERROR， 还 是 调用 ngx_http_next_header_filter(D) 继 续 处 理 ， 访 
者 可 以 参考 6.2.3 节 中 介绍 的 一 些 必需 的 过 滤 模 块 具备 的 功能 来 决定 。 


AR 
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竟 是 在 ngx_http_myfilter_header_filter 函 数 中 直接 


6.4.6 ”处 理 请 求 中 的 HTTP 包 体 


交 由 下 一 个 过 


返 


根据 图 6-3 中 摘 述 的 处 理 流 程 看 ，ngx_http_myfilter_ body_filter 回 调 
方法 的 实现 应 如 下 所 示 。 


static ngx_int_t 
ngx_http_myfilter_body_filter(ngx_http_request t *r, ngx_chain t *in) 
{ 


ngx_http_myfilter_ctx_t “EEX 
ctx = ngx_http_get module ctx(r, ngx_http_myfilter_module); 
/* 如 果 获 取 不 到 上 下 文 ， 或 者 上 下 文 结构 体 中 的 


add_prefix 为 


0 或 者 

2 时 ， 都 不 会 添加 前 级 ， 这 时 直接 交 给 下 一 个 
HTTP 过 滤 模 块 处 理 

*/ 


if (ctx == NULL || ctx->add_prefix != 1) { 
return ngx_http_next_body_filter(r, in); 


/* 将 


add_prefix 设 置 为 


2， 这 样 即使 


ngx_http_myfilter_body_filter 再 次 回调 时 ， 也 不 会 重复 添加 前 级 


4 
ctx->add_prefix = 2; 


// 从 请 求 的 内 存 池 中 分 配 内 存 ， 用 于 存储 字符 串 前 级 


ngx_buf_t* b = ngx_create temp_buf(r->pool, filter_prefix.1len); 
// 将 


ngx_buf_t 中 的 指针 正确 地 指向 


filter_prefix 字 符 串 


b->start = b->pos = filter_prefix.data; 
b->last = b->pos + filter_prefix.1en; 


/* 从 请 求 的 内 存 池 中 生成 
表 ， 将 刚 分 配 的 


ngx_chain_t 链 


ngx_buf_t 设 置 到 


buf 成 员 中 ， 并 将 它 添加 到 原先 待 发 送 的 


HTTP 包 体 前 


i 
ngx_chain_t *cl = ngx_alloc _ chain link(r->pool); 


cl->buf = b; 
cl->next = in,; 
// 调用 下 一 个 模块 的 


HTTP 包 体 处 理 方法 ， 注 意 ， 这 时 传 入 的 是 新 生成 的 


cl 链表 


return ngx_http_next_body_filter(r, cl); 


到 此 ， 一 个 简单 的 HTTP 过 滤 模 块 束 开 发 完成 了 。 无 论 功 能 多 么 复 
杂 的 HTTP 过 滤 模 块 ， 一 样 可 以 从 这 个 例子 中 衍生 出 来 。 


6.5 吉 % 洛 


通过 本 章 的 学 习 ， 读 者 应 该 已 经 掌握 如 何 编写 HTTP 过 滤 模 块 了 。 
相 比 普通 的 HTTP 处 理 模 块 ， 编 写 HTTP 过 滤 模 块 要 简单 许多 ， 因 为 它 
不 可 能 去 访问 第 三 方 服务 ， 也 不 负责 发 送 响应 到 客户 端 。HTTP 过 滤 模 
块 的 优势 在 于 三 加 ， 即 1 个 请 求 可 以 被 许多 HTTP 过 滤 模 块 处 理 ， 这 种 
设计 带 来 了 很 大 的 灵活 性 。 读 者 在 开发 HTTP 过 着 模块 时 ， 也 要 把 模块 
功能 分 解 得 更 单一 一 些 ， 即 在 功能 过 于 复杂 时 应 该 分 成 多 个 HITP 过 滤 
模块 来 实现 。 


第 7 草 ”Nginx 提 供 的 局 级 数据 结构 


任何 复杂 的 程序 都 需要 用 到 数组 、 链 表 、 树 等 数据 结构 ， 这 些 容 
器 可 以 让 用 户 忽略 底层 细节 ， 快 速 开 发 出 各 种 高 级 数据 结构 、 实 现 复 
杂 的 业务 功能 。 在 开发 Nginx 模 块 时 ， 同 样 也 需要 这 样 的 高 级 通用 容 
强 。 人 然而，Nginx 有 两 个 特点 : 跨 平 台 、 使 用 C 语 言 实现 ， 这 两 个 特点 
导致 Nginx 不 宜 使 用 一 些 第 三 方 中 间 件 提供 的 容器 和 算法 。 跨 平台 意味 
着 Nginx 必 须 可 以 运行 在 Windows、Linux 等 许多 主流 操作 系统 上 ， 因 
此 ，Nginx 的 所 有 代码 都 必须 可 以 跨 平台 编译 、 运 行 。 另 外 ，Nginx 是 
由 C 语 言 开发 的 。 虽 然 所 有 的 操作 系统 都 支持 C 语 言 ， 但 是 C 语 言 与 每 
一 个 操作 系统 都 是 强 相关 的 ， 且 C 库 对 操作 系统 的 某 些 系统 调用 封装 
的 方法 并 不 是 跨 平台 的 。 


屠 


对 于 这 种 情况 ，Nginx 的 解决 方法 很 简单 ， 在 这 些 必须 特殊 化 处 理 
的 地 方 ， 对 每 个 操作 系统 都 给 一 份 特 异化 的 实现 ， 因 此 ， 用 户 在 下 载 
Nginx 源 码 包 时 会 发 现 有 Windows 版 本 和 UNIX 版 本 。 而 对 于 基础 的 数 
据 结 构 和 算法 ，Nginx 则 完全 从 头 实 现 了 一 遍 ， 如 动态 数组 、 链 表 、 二 
又 排序 树 、 散 列表 等 。 当 开发 功能 复杂 的 模块 时 ， 如 果 需 要 使 用 这 些 
数据 结构 ， 不 妨 使 用 它们 来 加 快 开 发 速度 ， 这 些 数据 结构 的 好 处 是 完 
全 使 用 C 语 言 从 头 实现 ， 运 行 效 率 非常 高 ， 而 且 它 们 是 可 以 跨 平 台 使 
用 的 ， 在 主流 操作 系统 上 都 可 以 正常 的 工作 。 


当然 ， 由 于 这 些 基础 数据 结构 的 跨 平 台 特 性 、C 语 言 面 同 过 程 的 
特点 、 不 统一 的 使 用 风格 以 及 几乎 没有 注释 的 Nginx 源 代码 ， 造 成 了 它 
们 并 不 容易 使 用 ， 本 章 将 会 详细 曾 述 它们 的 设计 目的 、 思 想 、 使 用 方 
法 ， 并 通过 例子 形象 地 展示 这 些 容器 的 使 用 方式 。 


7.1 Nginx 提 供 的 高 级 数据 结构 概述 


本 章 将 介绍 Nginx 实 现 的 6 个 基本 容器 ， 熟 练 使 用 这 6 个 基本 容 右 ， 
将 会 大 大 提高 开发 Nginx 模 块 的 效率 ， 也 可 以 更 加 方便 地 实现 复 洒 的 功 


ngx_queue_t 双 回 链 表 是 Nginx 提 供 的 轻 量 级 链表 容 希 ， 它 与 Nginx 
的 内 存 池 无 关 ， 因 此 ， 这 个 链表 将 不 会 负 贡 分 配 内 存 来 存放 链表 元 
素 。 这 意味 着 ， 任 何 链表 元 素 都 需要 通过 其 他 方式 来 分 配 它 所 需要 的 
内 存 空间 ， 不 要 指望 ngx_queue_t 帮 助 存储 元 素 。ngx_queue_t 只 是 把 这 
些 已 经 分 配 好 内 存 的 元 素 用 双向 链表 连接 起 来 。ngx_queue _t 的 功能 
然 很 商 单 ， 但 它 非 常 轻 量 级 ， 对 每 个 用 户 数据 而 言 ， 只 需要 增加 两 个 
指针 的 空间 即 可 ， 消 耗 的 内 存 很 少 。 同 时 ，ngx_queue_t 还 提供 了 一 个 
非常 傈 易 的 插入 排序 法 ， 虽 然 不 太 适 合 超 大 规模 数据 的 排序 ， 但 它 胜 
在 简单 实用 。ngx_queue_t 作 为 C 语 言 提供 的 通用 双向 链表 ， 其 设计 思 
路 值得 用 户 参 考 。 


ngx_array_t 动 态 数组 类 似 于 C++ 语言 SITL 库 的 vector 容 句 ， 它 用 连 
续 的 内 存 存放 着 大 小 相同 的 元 素 (就 像 数组 ) ， 这 使 得 它 按 照 下 标 检 
索 数 据 的 效率 非常 高 ， 可 以 用 O(1) 的 时 间 来 访问 随机 元 素 。 相 比 数 
组 ， 它 的 优势 在 于 ， 数 组 通常 是 固定 大 小 的 ， 而 ngx_array_t 可 以 在 达 


到 容量 最 大 值 时 自动 扩容 (扩容 算法 与 常见 的 vector 容 器 不 同 ) 
ngx_array_t 与 ngx_queue_t 的 一 个 显 半 不同 点 在 于 ，ngx_queue_t 并 不 负 
责 为 容器 元 素 分 配 内 存 ， 而 ngx_array_t 是 负责 容器 元 素 的 内 存 分 配 

的 。ngx_array_t 也 是 Nginx 中 应 用 非常 广泛 的 数据 结构 ， 本 章 介绍 的 文 
持 通配符 的 散 列 表 中 就 有 使 用 它 的 例子 。 


ngx_list_t 单 向 链表 与 ngx_queue_t 双 癌 链 表 是 完全 不 同 的 ， 它 是 负 
贡 容 右 内 元 素 内 存 分 配 的 ， 因 此 ， 这 两 个 容 右 在 通用 性 的 设计 思路 上 
是 完全 不 同 的 。 同 时 它 与 ngx_array_t 也 不 一 样 ， 它 不 是 用 完全 连续 的 
内 存 来 存储 元 隶 ， 而 是 用 单 链 表 将 多 段 内 存 块 连接 起 来 ， 每 段 内 存 块 
也 存储 了 多 个 元 素 ， 有 点 像 数 组 + 单 链表 ”。 在 3.2.3 中 已 经 详细 介绍 
过 ngx_list_t 单 问 链 表 ， 本 章 不 再 资 述 。 


ngx_rbtree_t ( 红 黑 树 ) 是 一 种 非常 有 效 的 高 级 数据 结构 ， 它 在 许 
多 系统 中 都 作为 核心 数据 结构 存在 。 它 在 检索 特定 天 键 字 时 不 再 需要 
像 以 上 容器 那样 遍历 容器 ， 同 时 ，ngx_rbtree_t 容 器 在 检索 、 插 入 、 删 
除 元 素 方面 非常 高 效 ， 且 其 针对 各 种 类 型 的 数据 的 平均 时 间 都 很 优 
异 。 与 散 列 表 相 比 ，ngx_rbtree_t 还 文 持 范 围 查 询 ， 也 支持 高 效 地 遍历 
所 有 元 素 ， 因 此 ，Nginx 的 核心 模块 是 离 不 开 ngx_rbtree_t 容 右 有 的 。 同 
上 时， 一 些 较 复杂 的 Nginx 模 块 也 都 用 到 了 ngx_rbtree_t 容 器 。 用 户 在 需 
要 用 到 快速 检索 的 容 需 时 ， 应 该 百 和 多 考虑 是 不 是 使 用 ngx_rbtree t。 


ngx_radix_tree_t 基 数 树 与 ngx_rbtree_t 红 黑 树 一 样 都 是 二 又 查找 
树 ，ngx_rbtree_t 红 黑 树 具备 的 优点 ，ngx_radix_tree_t 基 数 树 同样 也 
有 ， 但 ngx_radix_tree_t 基 数 树 的 应 用 范围 要 比 ngx_rbtree_t 红 黑 树 小 ， 
为 ngx_radix_tree_t 要 求 元素 必 须 以 整 型 数据 作为 关键 字 ， 所 以 大 大 
减少 了 它 的 应 用 场景 。 然 而 ， 由 于 ngx_radix_tree_t 基 数 树 在 插入 、 删 
除 元 素 时 不 需要 做 旋转 操作 ， 因 此 它 的 插入 、 删 除 效 率 一 般 要 比 
ngx_rbtree_t 红 黑 树 高 。 选 择 使 用 哪 种 二 又 查找 树 取决 于 实际 的 应 用 场 
景 。 不 过 ，ngx_radix_tree_t 基 数 树 的 用 法 要 比 ngx_rbtree_t 红 黑 树 简单 


许多 。 


支持 通配符 的 散 列 表 是 Nginx 独 创 的 。Nginx 首 先 实 现 了 基础 的 常 
用 散 列 表 ， 在 这 个 基础 上 ， 它 义 根 据 Web 服 务 絮 的 符 点， 对 于 URI 域 名 
这 种 场景 设计 了 支持 通配符 的 散 列 表 ， 当 然 ， 只 支持 前 置 通配符 和 后 
置 通配符 ， 如 www.test.* 和 *.test.com。Nginx 对 于 这 种 散 列 表 做 了 非常 
多 的 优化 设计 ， 它 的 实现 较为 复杂 。 在 7.7 市 中 ， 将 会 非常 详细 地 描述 
它 的 实现 ， 当 然 ， 如 果 只 是 使 用 这 种 散 列 表 ， 并 不 需要 完全 看 懂 7.7 
节 ， 可 以 只 看 一 下 7.7.3 市 的 例子 ， 这 将 会 简单 许多 。 不 过 ， 要 想 能 够 
灵活 地 修改 Nginx 的 各 种 使 用 散 列 表 的 代码 ， 还 是 建议 读者 仔细 阅读 一 
下 7.7 节 的 内 容 。 


7.2 ngx_queue_t 双 回 链 表 


ngx_queue_t 是 Nginx 提 供 的 一 个 基础 顺序 容器 ， 它 以 双向 链表 的 方 
式 将 数据 组 织 在 一 起 。 在 Nginx 中 ，ngx_queue_t 数 据 结构 被 大 量 使 用 ， 
下 面 将 详细 介绍 它 的 特点 、 用 法 。 


7.2.1 为 什么 设计 ngx_queue _t 双 同 链 表 


链表 作为 顺序 容 恬 的 优势 在 于 ， 它 可 以 高 效 地 执行 插入 、 删 除 、 
合并 等 操作 ， 在 移动 链表 中 的 元 素 时 只 需要 修改 指针 的 指向 ， 因 此 ， 
筷 很 适合 频 迷 修 改 容 郁 的 场合 。 在 Nginx 中 ， 链 表 坪 必 不 可 少 的 ， 而 
ngx_queue_t 双 癌 链 表 束 被 设计 用 于 达成 以 上 目的 。 


相对 于 Nginx 其 他 顺序 容器 ，ngx_queue_t 容 器 的 优势 在 于 : 
实现 了 排序 功能 。 


它 非 党 轻 量 级 ， 是 一 个 纯粹 的 双 同 链表 。 它 不 负责 链表 元 系 所 占 
内 存 的 分 配 ， 与 Nginx 封 疼 的 ngx_pool t 内 存 池 完 全 无 和 天 。 


文 持 两 个 链表 间 的 合并 。 


ngx_gueue_t 容 器 的 实现 只 用 了 一 个 数据 结构 ngx_queue_t， 它 仪 有 
两 个 成 员 : prev、next， 如 下 所 示 : 


typedef struct ngx_queue_s ngx_queue_t; 
struct ngx_queue_s { 

ngx_queue_t *prev; 

ngx_queue tt *next; 


因此 ， 对 于 链表 中 的 每 个 元 素来 说 ， 空 间 上 只 会 增加 两 个 指针 的 
内 存 消耗 。 


使 用 ngx_queue_t 时 可 能 会 过 到 有 些 让 人 费解 的 情况 ， 因 为 链表 容 
妖 目 身 是 使 用 ngx_gqueue_t 来 标识 的 ， 而 链表 中 的 每 个 元 素 同样 使 用 
ngx_queue_t 结 构 来 标识 自己 ， 并 以 ngx_queue_t 结 构 维 持 其 与 相 邻 元 素 
的 关系 。 下 面 开始 介绍 ngx_queue_t 的 使 用 方法 。 


7.2.2” 双 辣 链 表 的 使 用 方法 


Nginx 在 设计 这 个 双 辐 链表 时 ， 由 于 容 亏 与 元 素 共用 了 ngx_queue ft 
结构 体 ， 为 了 避免 ngx_queue _t 结 构 体 成 员 的 意义 混乱 ，Nginx 封 装 了 链 
表 容 絮 与 元 素 的 所 有 方法 ， 这 种 情况 非 第 少见 ， 而 且 从 接 下 来 的 几 市 
中 可 以 看 到 ， 其 他 容器 都 需要 直接 使 用 成 员 变 量 来 访问 ， 唯 有 
ngx_queue_t 双 问 链 表 只 能 使 用 独 7-1 中 列 出 的 方法 访问 容 需 。 


ngx queue { 容 送 
Hprev 
+next 


gx queue init() ee 
queue empty () ngx_queue _t 容 天 中 的 元 秒 


gueue insert head() 
queue insert tail() 
queue head () Hnex queue next () 
queue last() Hngx gueue prev () 
gx gueue sentinel() Fngx queue data () 
yx queue remove () Fngx queue insert after () 
queue splt (0) 
queue add () 
queue middle () 
queue sort() 


图 7-1 ”ngx_queue t 容 器 提供 的 操作 方法 


使 用 双向 链表 容器 时 ， 需 要 用 一 个 hgx_queue_t 结 构 体 表示 容器 本 
身 ， 而 这 个 结构 体 共 有 12 个 方法 可 供 使 用 ， 表 7-1 中 列 出 了 这 12 个 方法 
的 意义 。 


表 7-1 ngx_queue_{t 双 向 链表 容器 所 文 持 的 方法 


方法 名 执行 意义 
h 为 链表 容器 结构 体 ngx_queue t| 将 链表 容器 初始 化 ， 这 时 会 自动 置 为 空 
的 指针 链表 
险 测 链表 容器 中 是 否 为 空 ， 即 是 否 没有 
个 元 素 存在 。 如 果 返 回 非 0， 表 示 链 表 了 是 
空 的 


ngx queue init(h) 


h 为 链表 容器 结构 体 ngx_queue _t 
的 指针 


ngx_queue_ empty(h) 


h 为 链表 容器 结构 体 ngx_queue __ 
t 的 指针 ，x 为 插入 元 素 结构 体 中 
针 
h 为 链表 容器 结构 体 ngx_queue_ 

ngx_queue insert tailth. x) ”|t 的 指针 ， x 为 插入 元 素 结构 体 中 | 将 元 素 x 添加 到 链表 容器 h 的 末尾 
ngx_queue t 成 员 的 指针 

h 为 链表 容器 结构 体 ngx_queue t| 返回 链表 容 絮 hh 中 的 第 一 个 元 素 的 ngx_ 
的 指针 queue_t 结构 体 指针 

h 为 链表 容器 结构 体 ngx_queue t| 返回 链表 容器 中 的 最 后 一 个 元 素 的 ngx_ 
的 指针 queue_t 结构 体 指 针 


ngx_queue insert_head(h, x) 将 元 素 x 插入 到 链表 容器 了 的 头 部 


ngx_queue t 成 员 的 指 


ngx_queue head(h) 


ngx queue last(h) 


h 为 链表 容器 结构 体 ngx_queue_t 
的 指针 


x 为 插入 元 素 结 构 体 中 ngx_ 


返回 链表 容器 结构 体 的 指针 


ngx queue_ sentinel(h) 


ngx queue remove(x) 


queue ft 成 员 的 指针 


( 续 ) 


Rr 
ngx_queue_split 用 于 拆 分 链表 , h 是 链表 
容器 ， 而 q 是 链表 h 中 的 一 个 元 素 。 这 个 方 
h 为 链表 容器 结构 体 ngx_queue t| 法 将 链表 h 以 元 素 dq 为 界 拆 分 成 两 个 链表 h 
的 指针 和 aa， 其 中 h 由 原 链 表 的 前 半 部 分 构成 (不 包 
括 q)， 而 na 由 原 链表 的 后 半 部 分 构成 , q 是 
它 的 首 元 素 


ngX_queue_split(h, q, D) 


h 为 链表 容器 结构 体 ngx_queue_ 
ngx_queue add(h., n) t 的 指针 ，n 为 男 一 个 链表 容器 结构 | 合并 链表 ， 将 n 链表 添加 到 h 链表 的 末尾 
体 ngx_queue t 的 指针 

返回 链表 中 心 元 素 ， 如 ， 链表 共 有 个 元 

h 为 链表 容器 结构 体 ngx_queue t| 素 ，ngx_queue middle 方法 将 返回 第 N/2+1 
的 指针 个 元 素 。 例 如 ， 链 表 有 4 个 元 素 ， 将 会 返回 
第 3 个 元 素 (不 是 第 2 个 元 素 ) 

h 为 链表 容器 结构 体 ngx_queue_| 使 用 插入 排序 法 对 链表 进行 排序 ，cmpfunc 
t 的 指针 ，cmpfunc 是 两 个 链表 元 素 | 需要 使 用 者 自己 实现 ， 它 的 原型 是 这 样 的 : 
的 比较 方法 ， 如 果 它 返回 正 数 ， 则 |ngx_int t (*cmpfunc)(const ngx_queue_t *， 
表示 以 升序 排序 const ngX_queue t#) 


ngx queue middle(h) 


ngx_ queue_sort(h,cmpfunc) 


对 于 链表 中 的 每 一 个 元 素 ， 其 类 型 可 以 是 任意 的 struct 结 构 体 ， 但 
这 个 结构 体 中 必须 要 有 一 个 ngx_queue_t 类 型 的 成 员 ， 在 向 链表 容器 中 
深 加 、 删 除 元 又 时 都 古 使 用 的 结构 体 中 ngx_queue_t 类 型 成 员 的 指针 。 
当 ngx_queue_t 作 为 链表 的 元 聚 成 员 使 用 时 ， 它 具有 表 7-2 中 列 出 的 4 种 
方法 。 


表 7-2 ngx_qdueue_{t 双 回 链 表 中 的 元 素 所 文 持 的 方法 


方法 名 执行 意义 
q 为 链表 中 某 一 个 元 素 结构 体 的 ngx_ 


queue t 成 员 的 指针 


ngx queue next(q) 返回 gq 元素 的 下 一 个 元 素 
2xX_ dg 如 q q 


q 为 链表 中 -个 元 素 结 构 体 的 ngx_ 
queue t 成 员 上 
qd 为 链表 中 某 一 个 元 素 结构 体 的 ngx_ 
queue t 成 员 的 指针 ，type 为 链表 元 素 的 结 
ngx_queue_data(q. type, link) ”| 构 体 类 型 名 称 (该 结构 体 中 必须 包含 ngx_ 
queue t 类 型 的 成 员 )，link 是 上 面 这 个 结构 

体 中 ngx_queue t 类 型 的 成 员 名 字 
qd 为 链表 中 某 个 元 素 结 构 体 的 ngx_ 


ngx queue insert after(q, x) queue t 成员 的 指针 ，x 为 插入 元 素 结构 体 | 将 元 素 x 插入 到 元 素 q 之 后 


ngx queue prev(q) 返回 q 元 素 的 上 一 个 元 素 

返回 gq 元素 (ngx_queue t 类 型 ) 
所 属 结构 体 (任何 struct 类 型 ， 其 
中 可 在 任意 位 置 包含 ngx_queue t 
类 型 的 成 员 ) 的 地 址 


中 ngx_queue t 成 员 的 指针 


在 表 7-1 和 表 7-2 中 ， 已 经 列 出 了 链表 支持 的 所 有 方法 ， 下 面 将 以 一 
个 简单 的 例子 来 说 明 如 何 使 用 ngx_gqueue_t 双 辣 链 表 。 


7.2.3 ”使 用 双向 链表 排序 的 例子 


本 世 定 义 一 个 简单 的 链表 ， 并 使 用 ngx_queue_sort 方 法 对 所 有 元 素 
排序 。 在 这 个 例子 中 ， 可 以 看 到 如 何 定 义 、 初 始 化 ngx_queue _t 容 器 ， 


如 何 定义 任意 类 型 的 链表 元 素 ， 如 何 遍 历 链 表 ， 如 何 自 定义 排序 方法 
并 执行 排序 。 


首先 ， 定 义 链表 元 素 的 结构 体 ， 如 下 面 的 TestrNode 结 构 体 : 


typedef struct { 
u_char* str; 
ngx_queue_t qEle,; 
int num; 

} TestNode; 


链表 元 素 结构 体 中 必须 包含 ngx_queue_t 类 型 的 成 员 ， 当 然 它 可 以 


在 任意 的 位 置 上 。 本 例 中 它 的 上 面 有 一 个 char* 指 针 ， 下 面 有 一 个 整 型 
成 员 num， 这 样 是 允许 的 。 


排序 方法 需要 自 定 义 。 下 面 以 TestNode 结 构 体 中 的 num 成 员 作 为 排 
序 依据 ， 实 现 compTestNode 方 法 作为 排序 过 程 中 任意 两 元 素 间 的 比较 
方法 。 


ngx_int_t compTestNode(const ngx_queue t* a, const ngx_queue _t* b) 


/* 首 先 使 


ngx_queue_data 方 法 


ngx_queue_t 变 量 获取 元 素 结 构 体 
TestNode 的 地 址 


#7 
TestNode* aNode 
TestNode* bNode 
// 返 蕊 


ngx_queue_data(a, TestNode, dqEle); 
ngx_queue_data(b, TestNode, qEle); 


num 成 员 的 比较 结果 


return aNode->num > bNode->num; 


这 个 比较 方法 结合 ngx_queue_sort 方 法 可 以 把 链表 中 的 元 素 按照 
num 的 大 小 以 升序 排列 。 在 此 例 中 ， 可 以 看 到 ngx_queue_data 的 用 法 ， 
即 可 以 根据 链表 元 素 结构 体 TestNode 中 的 qEle 成 员 地 址 换算 出 TestNode 
结构 体 变量 的 地 址 ， 这 是 面 同 过 程 的 C 语 言 编写 的 ngx_gueue_t 链 表 之 所 
以 能 够 通用 化 的 关键。 下 面 来 看 一 下 ngx_queue_data 的 定义 : 


#define ngx_dqueue_data(dq,type, Link) \ 
(type *) ((u_char *) q - offsetof(type, link)) 


在 4.2.2 廊 中 曾经 提 到 过 offsetof 函 数 症 如 何 实现 的 ， 即 它 会 返回 link 
成 员 在 type 结 构 体 中 的 偏 移 量 。 例 如 ， 在 上 例 中 ， 可 以 通过 
ngx_gueue_t 类 型 的 指针 减 去 qEle 相 对 于 TestNode 的 地 址 偏 移 量 ， 得 到 
TestNode 结 构 体 的 地 址 。 


下 面 开 始 定义 双 同 链表 容器 queueContainer， 并 将 其 初始 化 为 空 链 
表 ， 如 下 所 示 。 


ngx_queue_t queueContainer; 
ngx_queue_init(&queueContainer ); 


链表 容器 以 ngx_queue_t 定 义 即 可 。 注 意 ， 对 于 表示 链表 容器 的 
ngx_queue_t 结 构 体 ， 必 须 调 用 ngx_queue_init 进 行 初 始 化 。 


ngx_queue_t 双 办 链表 是 完全 不 负责 分 配 内 存 的 ， 每 一 个 链表 元 素 
必须 自己 管理 自己 所 占用 的 内 存 。 因 此 ， 本 例 在 进程 栈 中 定义 了 5 个 


TestNode 结 构 体 作为 链表 元 素 ， 并 把 它们 的 num 成 员 初 始 化 为 0、1、 
2、3、4， 如 下 所 示 。 


int i = 0; 
TestNode node[5]; 
for (; i < 5; i++) 


node[il].num = i; 


下 面 把 这 5 个 TestNode 结 构 体 添加 到 queueContainer 链 表 中 ， 注 意 ， 
这 里 同时 使 用 了 ngx_queue_insert_tail 、 ngx_queue_insert_head 、 
ngx_queue_insert_after 3 个 添加 方法 ， 读 者 不 妨 思考 一 下 链表 中 元 素 的 
顺序 是 什么 样 的 。 


ngx_queue_insert_tail(&queueContainer, &node[0].qEle); 
ngx_queue_insert_head(&queueContainer, &node[1].qEle); 
ngx_queue_insert_tail(&queueContainer, &node[2].qEle); 
ngx_queue_insert_after(&queueContainer, &node[3] .dqEle); 
ngx_queue_insert_tail(&queueContainer, &node[4].qdEle); 


根据 表 7-1 中 介绍 的 方法 可 以 得 出 ， 如 果 此 时 的 链表 元 素 顺 序 以 
num 成 员 标 识 ， 那 么 应 该 是 这 样 的 : 3、1、0、2、4。 如 果 有 疑问 ， 不 
妨 写 个 所 历 链表 的 程序 检验 一 下 顺序 是 否 如 此 。 下 面 束 根据 表 7-1 中 的 
方法 说 明 编写 一 段 简 单 的 所 历 链 表 的 程序 。 


ngx_queue_t* q; 

for (q = ngx_queue_head(&queueContainer ) ; 
dq != ngx_queue_sentinel(&queueContainer ) ， 
dq = ngx_queue_next(9q)) 


TestNode* eleNode = ngx_queue data(q, TestNode, dqEle); 
// 处 理 当 前 的 链表 元 素 


eleNode 


上 面 这 段 程序 将 会 依次 从 链表 头 部 遍历 到 尾部 。 反 向 遇 历 也 很 简 
单 。 读 者 可 以 党 试 使 用 ngx_queue_last 和 ngx_queue_prev 方 法 编写 相关 
代码 。 


下 面 开 始 执行 排序 ， 代 码 如 下 所 示 。 


ngx_queue_sort(&queueContainer, compTestNode); 


这 样 ， 链 表 中 的 元 素 就 会 以 0、1、2、3、4 (num 成 员 的 值 ) 的 升 
序 排列 了 。 


表 7-1 中 列 出 的 其 他 方法 束 不 在 这 里 一 一 举例 了 ， 使 用 方法 非常 相 
人 


7.2.4 双 回 链表 是 如 何 实现 的 


本 廊 将 说 明 ngx_gqueue_t 链 表 容 絮 以 及 元 到 中 prev 成 员 、next 成 员 的 
意义 ， 整 个 链表 就 是 通过 这 两 个 指针 成 员 实 现 的 。 


下 面 先 来 看 一 下 ngx_queue_t 结 构 体 作为 容器 时 其 prev 成 员 、next 成 
员 的 意义 。 当 容器 为 空 时 ，prev 和 next 都 将 指 癌 容器 本 身 ， 如 图 7-2 所 
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如 图 7-2 所 示 ， 如 采 在 某 个 结构 体 中 定义 了 ngx_queue t 容 右 ， 其 
prev 指 针 和 next 指 针 都 会 指 癌 ngx_queue _t 成 员 的 地 址 。 


£ 


DH .Fr 
容 症 是 空 的 


图 7-2 ”至 容 需 时 ngx_queue_t 结 构 体 成 员 的 值 


当 容 峰 不 为 空 时 ，ngx_queue_t 容 器 的 next 指 针 会 指向 链表 的 第 1 个 
元 素 ， 而 prev 指 针 会 指向 链表 的 最 后 1 个 元 素 。 如 图 7-3 所 示 ， 这 时 链表 
中 只 有 1 个 链表 元 素 ， 容 需 的 next 指 针 和 prev 指 针 都 将 指 同 这 个 唯一 的 
链表 元 素 。 


nexX_dueue_t ngx_dqueue_1 


ngx_dueue 工 容 融 容 带 只 有 1 个 元 素 


图 7-3 ” 当 仅 含 1 个 元 素 时 ， 容 器 、 元 素 中 的 ngx_queue_t 结 构 体 成 员 的 
值 


对 于 每 个 链表 元 素来 说 ， 其 prev 成 员 都 指向 前 一 个 元 素 (不 存在 时 
指向 链表 容器 ) ， 而 next 成 员 则 指向 下 一 个 元 素 (不 存在 时 指向 链表 容 
器 ) ， 这 在 图 7-3 中 可 以 看 到 。 


当 容 絮 中 有 了 两 个 元 素 时 ，prev 和 next 的 指 问 如 图 7-4 所 示 。 


ngx_queue1 容 带 容器 中 的 第 1 个 元 素 容器 中 的 第 2 个 元 素 
图 7-4” 当 含有 两 个 或 多 个 元 素 时 ， 容 器 、 元 素 中 的 ngx_queue_t 结 构 体 
中 prev 、 next 成 员 的 值 


图 7-4 很 好 地 诠释 了 前 面 的 定义 ， 容 器 中 的 prev 成 员 指 同 最 后 1 个 也 
就 是 第 2 个 元 素 ，next 成 员 指 向 第 1 个 元 素 。 第 1 个 元 素 的 prev 成 员 指 同 
容器 本 喘 ， 而 其 next 成 员 指 回 第 2 个 元 素 。 第 2 个 元 素 的 prev 成 员 指 回 第 
1 个 元 素 ， 其 next 成 员 则 指 癌 容器 本 里 。 
ngx_queue ft 的 实现 就 是 这 


文 么 简单 ， 但 它 的 排序 算法 ngx_queue_sort 
使 用 的 插入 排序 ， 并 不 适合 为 庞大 的 数据 排序 。 


7.3 ngx_array_t 动 仿效 组 


ngx_array_t 是 一 个 顺序 容器 ， 它 在 Nginx 中 大 量 使 用 。ngx_array_t 
容 絮 以 数组 的 形式 存储 元 素 ， 并 支持 在 达到 数组 容量 的 上 限时 动态 改 
变数 组 的 大 小 。 


7.3.1 为 什么 设计 ngx_array_t 动 态 数 组 


数组 的 优势 是 它 的 访问 速度 。 由 于 它 使 用 一 块 完整 的 内 存 ， 并 按 
照 固定 大 小 存储 每 一 个 元 素 ， 所 以 在 访问 数组 的 任意 一 个 元 素 时 ， 都 
可 以 根据 下 标 直 接 寻 址 找到 它 ， 男 外 ， 数 组 的 访问 速度 钙 常 量 级 的 ， 
在 所 有 的 数据 结构 中 它 的 速度 都 是 最 快 的 。 然 而 ， 正 是 由 于 数组 使 用 
一 块 连续 的 内 存 存储 所 有 的 元 素 ， 所 以 它 的 大 小 直接 决定 了 所 消耗 的 
内 存 。 可 见 ， 如 有 果 预 分 配 的 数组 过 大 ， 肯 定 会 当 费 宝贵 的 内 存 资源 。 
那么 ， 数 组 的 大 小 究竟 应 该 分 配 多 少 才 是 够 用 的 呢 ? 当 数 组 大 小 无 法 
确定 时 ， 动 态 数 组 吏 “ 登 场 " 了 。 


C++ 语 言 的 STL 中 的 vector 容 右 束 像 ngx_array_t 一 样 是 一 个 动态 数 
组 。 它 们 在 数组 的 大 小 达到 已 经 分 配 内 存 的 上 限时 ， 会 目 动 扩充 数组 
的 大 小 。 具 备 了 这 个 特点 之 后 ，ngx_array_t 动 态 数 组 的 用 处 就 大 多 了 ， 


而 且 它 内 置 了 Nginx 封 装 的 内 存 池 ， 因 此 ， 它 分 配 的 内 存 也 是 在 内 存 池 
中 申请 得 到 。ngx_array_t 容 器 具备 以 下 3 个 优点 : 


:访问 速度 快 。 
:允许 元 素 个 数 具备 不 确定 性 。 


责 元 素 占 用 内 存 的 分 配 ， 这 些 内 存 将 由 内 存 池 统一 管理 


7.3.2 ”动态 数组 的 使 用 方法 


ngx_array_t 动 态 数 组 的 实现 仅 使 用 1 个 结构 体 ， 如 下 所 示 。 


typedef struct ngx_array_s ngx_array_t; 
struct ngx_array_s 
// elts 指 向 数组 的 首 地 址 


void *elts; 
// nelts 是 数组 中 已 经 使 用 的 元 素 个 数 


ngx_uint_t nelts,; 


// 每 个 数组 元 素 占用 的 内 存 大 小 


size_t 


size; 
// 当前 数组 中 能 够 容纳 元 素 个 数 的 总 大 小 


ngx_uint_t nalloc; 


// 内 存 池 对 象 


ngx_pool t *pool,; 
}; 


在 上 面 这 段 代 码 中 已经 简单 描述 了 ngx_array_t 结 构 体 中 各 成 员 的 意 
义 ， 通 过 图 7-5， 读 者 可 以 有 更 直观 的 理解 。 


共 分 配 了 nalloc 个 元 素 


已 经 存储 了 nelts 个 元 素 


ngx array t 


+elts 
elts 指 问 动态 数组 的 首 地 址 +nelts 

+ siZe 

+nalloc 

+ pool 


array create () 


array init () 
array destroy () 
array push() 
array push n() 


图 7-5 ”ngx_array_t 动 态 数 组 结构 体 中 的 成 员 及 其 提供 的 方法 


从 图 7-5 中 可 以 看 出 ，ngx_array_t 动 态 数组 还 提供 了 5 个 基本 方法 ， 
它们 的 意义 见 表 7-3。 


表 7-3 ngx_array_t 动 态 数 组 提供 的 方法 


方 汪 i 


ngx atray_create(ngx_pool t *p， 


ngx uint tn, size t size) 
个 元 素 所 占用 的 内 存 大 小 


DgX_alTay_init(DngX_alTay_t *a, 


是 内 存 池 , n 是 初始 分 配 en 
PD 是 由 有 有 半分 配 | 创建 1 个 动态 数组 ， 


元 素 的 最 大 个 数 ，size 是 每 一 a ole 
SO 是 为 size 的 内 存 空间 


是 一 个 动态 数组 结 由 体 的 


ngx_ pool t *p. ngx_uint tn, size tsize) | 分 RE 最 大 


ngx array_destroy(ngx array_t *a) 


方法 名 


ngx array push(nex array_ t *a) 


每 一 个 元 素 所 占用 的 内 存 jh 


-个 动态 数组 结构 体 的 


向 当前 a 动态 数组 
回 的 是 这 个 新 添加 元 
果 动 态 数 组 已 经 达到 


ngx_ array_push n(ngx array_t *a., 


动 扩容 ， 到 底 扩 容 多 
说 明 


ngx_ uint tn) 


汗 ，n 是 需要 添加 元 素 的 个 数 “| 的 是 新 添加 这 批 元 素 中 


并 预 分 配 n 个 大 小 


直 内 存 池 ， i 初始 化 1 个 已 经 存在 的 动态 数组 ， 并 预 
Py size 是 | 分 配 m 个 大 小 为 size 的 内 存 空间 


销毁 已 经 分 配 的 数组 元 素 空间 和 ngx_ 
array t 动态 数组 对 象 
destroy 最 好 与 ngx_array_create 配对 使 用 ， 
因为 ngx array_destroy 同 时 会 回收 ngx_ 


array_t 结构 体 自身 占用 的 内 存 


注意 : ngx_array_ 


执行 意义 

中 添加 1 个 元 素 ， 返 
素 的 地 址 。 注 意 : 如 
容量 上 限 ， 这 时 会 自 
少 字 节 ， 在 7.3.4 节 中 


-个 动态 数组 结构 体 的 指 | 向 当前 a 动态 数组 中 添加 1 个 元 素 ， 返回 


第 一 个 了 E 素 的 地 址 


如 果 使 用 已 经 定义 过 的 ngx_array_t 结 构 体 ， 那 么 可 以 先 调用 
ngx_array_init 方 法 初始 化 动态 数组 。 如 果 要 重新 在 内 存 池 上 定义 
ngx_array_t 结 构 体 ， 则 可 以 调用 ngx_array_create 方 法 创建 动态 数组 。 
两 个 方法 都 会 预 分 配 一 定 容量 的 数组 元 素 。 


在 向 动态 数组 中 添加 新 元 素 时 ， 最 好 调用 ngx_array_push 或 者 
ngx_array_push_n 方 法 ， 这 两 个 方法 会 在 达到 数组 预 分 配 


动 扩容 ，j 


这 比 直接 操作 ngx_array_t 结 构 体 中 的 成 员 要 好 得 


7.3.3 市 的 例子 中 详细 说 明 。 


容量 上 限时 自 
多 ， 具体 将 在 


@ 注音 ”因为 ngx_array_destroy 是 在 内 存 池 中 销毁 动态 数组 及 其 
分 配 的 元 素 内 存 的 (如果 动态 数组 的 ngx_array t 结 构 体内 存 是 利用 栈 等 
非 内 存 池 方式 分 配 ， 那 么 调用 ngx_array_destroy 会 导致 不 可 预 估 的 错 
误 ) ， 所 以 它 必 须 与 ngx_array_create 配 对 使 用 。 


7.3.3 ”使 用 动态 数组 的 例子 


本 和 以 一 个 简单 的 例子 说 明 如 何 使 用 动态 数组 。 这 里 仍然 以 7.2.3 
中 介绍 的 TestNode 作 为 数组 中 的 元 聚 类 型 。 上 首先 ， 调 用 ngx_array_create 
方法 创建 动态 数组 ， 代 码 如 下 。 


ngx_array_t* dynamicArray = ngx_array_create(cf->pool, 1, sizeof(TestNode)); 


这 里 创建 的 动态 数组 只 预 分 配 了 1 个 元 素 的 空间 ， 每 个 元 素 占 用 的 
内 存 字 节 数 为 sizeof(TestrNode)， 也 就 是 TestrNode 结 构 体 占用 的 空间 大 


小 。 


然后 ， 调 用 ngx_array_push 方 法 向 dynamicArray 数 组 中 添加 两 个 元 
素 ， 代 人 码 如 下 。 


TestNode* a = ngx_array_push(dynamicArray ) ， 
a->num = 工 ; 

a = ngx_array_push(dynamicArray ) ， 

a->num = 2; 


这 两 个 元 素 的 num 值 分 别 为 L 和 2。 注 意 ， 在 添加 第 2 个 元 素 时 ， 实 
际 已 经 发 生 过 一 次 扩容 了 ， 因 为 调用 ngx_array_create 方 法 时 只 预 分 配 
了 1 个 元 素 的 空间 。 下 面 党 试用 ngx_array_push_n 方 法 一 次 性 添加 3 个 元 
素 ， 代 码 如 下 。 


TestNode* b = ngx_array_push_n(dynamicArray, 3); 
b->num = 3， 
(b+1)->num 
(b+2)->num 


4; 
5; 


这 3 个 元 素 的 num 值 分 别 为 3、4、5。 下 面 来 看 一 下 是 如 何 裔 历 
dynamicArray 动 态 数 组 的 ， 代 码 如 下 。 


TestNode* nodeArray = dynamicArray->elts,; 
ngx_uint_t arraySed = 0; 
for (; arraySeq < dynamicArray->nelts,; arraySeq++) 
{ 

a = nodeArray + arraySedq; 

// 下 面 处 理 数 组 中 的 元 素 


了 解 了 通 历 dynamicArray 动 态 数组 的 方法 后 ， 再 来 看 一 下 销毁 动态 
数组 的 方法 ， 这 就 非常 简单 了 ， 如 下 所 示 : 


ngx_array_destroy(dynamicArray); 


7.3.4 ”动态 数组 的 扩容 方式 


本 下 将 介绍 当 动 态 数 组 达到 容量 上 限时 是 如 何 进行 扩容 的 。 
ngx_array_push 和 和 ngx_array_push_n 方 法 都 可 能 引发 扩容 操作 。 


当 已 经 使 用 的 元 素 个 数 达 到 动态 数组 预 分 配 元 素 的 个 数 时 ， 再 次 
调用 ngx_array_push 或 者 ngx_array_push_n 方 法 将 引发 扩容 操作 。 
ngx_array_push 方 法 会 申请 ngx_array_t 结 构 体 中 size 字 节 大 小 的 内 存 ， 而 
ngx_array_push_n 方 法 将 会 申请 n \n 是 ngx_array_push_n 的 参数 ， 表 示 需 
要 添加 n 个 元 素 ) 个 size 字 市 大 小 的 内 存 。 每 次 扩容 的 大 小 将 受制 于 内 
存 池 的 以 下 两 种 情形 : 


如果 当 前 内 存 池 中 剩余 的 空间 大 于 或 者 等 于 本 次 需要 新 增 的 空 
间 ， 那 么 本 次 扩容 将 只 扩充 新 增 的 空间 。 例 如 ， 对 于 ngx_array_push 方 
法 来 说 ， 就 是 扩充 1 个 元 素 ， 而 对 于 ngx_array_push_n 方 法 来 说 ， 就 是 
扩充 n 个 元 素 。 


如果 当 前 内 存 池 中 剩余 的 空间 小 于 本 次 需要 新 增 的 空间 ， 那 么 对 
ngx_array_push 方 法 来 说 ， 会 将 原先 动态 数组 的 容量 扩容 一 倍 ， 而 对 于 
ngx_array_push_n 来 说 ， 情 况 更 复杂 一 些 ， 如 采 参 数 n 小 于 原先 动态 数 
组 的 容量 ， 将 会 扩容 一 倍 ; 如 条 参数 n 大 于 原 移动 态 数组 的 容量 ， 这 时 
会 分 配 2xn 大 小 的 空间 ， 扩 容 会 超过 一 信 。 这 体现 了 Nginx 预 佑 用 户 行 
为 的 设计 思想 。 


在 以 上 两 种 情形 下 扩容 的 字 节 数 都 与 每 个 元 素 的 大 小 相关 。 


@ 注意 “上 壕 第 ?种 情形 涉及 数据 的 复制 。 新 扩容 一 倍 以 上 的 动 
态 数组 将 在 全 痢 的 内 存 块 上 ， 这 时 将 有 一 个 步骤 将 原 动 态 数组 中 的 元 
素 复 制 到 新 的 动态 数组 中 ， 当 数组 非常 大 时 ， 这 个 步骤 可 能 会 耗 时 较 
jg 


7.4 ngx_list_t 单 癌 链 表 


它 实 际 上 相当 于 7.3 节 中 介绍 的 动态 


ngx_list_t 也 是 一 个 顺序 容 侨 ， 它 实 
数组 与 单 向 链表 的 结合 体 ， 只 是 扩容 起 来 比 动态 数组 简单 得 多 ， 它 可 
容器 中 各 成 员 的 意 


全 
以 一 次 性 扩容 1 个 数组 。 在 图 3-2 中 摘 述 了 ngx_list_t 
义 ， 而 且 在 3.2.3 节 中 详细 介绍 过 它 的 用 法 ， 这 里 不 再 费 述 。 


7.5 ngx_rbtree_t 红 墨 树 


ngx_rbtree_t 是 使 用 红 黑 树 实现 的 一 种 关联 容器 ，Nginx 的 核心 模块 
(如 定时 右 管 理 、 文 件 缓存 模块 等 ) 在 需要 快速 检索 、 和 查找 的 场合 下 
都 使 用 了 ngx_rbtree_t 容 器 ， 本 节 将 系统 地 讨论 ngx_rbtree_t 的 用 法 ， 并 
以 一 个 贯穿 本 市 始终 的 例子 对 它 进 行 说 明 。 在 这 个 例子 中 ， 将 有 10 个 
元 素 和 需要 存储 到 红 黑 树 窗口 中 ， 每 个 元 素 的 关键 字 是 简单 的 整 型 ， 分 
别 为 1、6、8、11、13、15、17、22、25、27， 以 下 的 例子 中 都 会 使 用 


到 这 10 个 节点 数据 。 
7.5.1 为 什么 设计 ngx_rbtree_t 红 黑 树 


上 文 介 绍 的 容器 都 是 顺序 容器 ， 它 们 的 检索 效率 通常 情况 下 都 比 
较 差 ， 一 般 只 能 明 历 检索 指定 元 素 。 当 需要 容器 的 检索 速度 很 快 ， 或 
者 需要 支持 范围 查询 时 ，ngx_rbtree_t 红 黑 树 容器 是 一 个 非常 好 的 选 


择 。 


红 黑 树 实际 上 是 一 种 目 平衡 二 叉 查 找 树 ， 但 什么 是 二 义 树 呢 ? 二 
又 树 是 每 个 下 点 最 多 有 两 个 子 树 的 树 结构 ， 每 个 斑点 都 可 以 用 于 存储 
数据 ， 可 以 由 任 1 个 太 扩 访问 它 的 左右 子 树 或 者 父 节 上 后。 


那么 ， 什 么 是 二 又 碍 找 树 呢 ? 二 又 查找 树 或 者 是 一 棵 空 树 ， 或 者 
是 具 有 下 列 性 质 的 二 又 树 。 


-每 个 节点 都 有 一 个 作为 查找 依据 的 关键 码 (key) ， 所 有 节点 的 关 
键 码 互 不 相同 。 


- 左 子 树 (如 果 存在 ) 上 所 有 市 点 的 关键 码 都 小 于 根 市 点 的 关键 
码 。 


右 子 树 (如 果 存在 ) 上 所 有 节点 的 关键 码 都 大 于 根 节点 的 关键 
码 。 


: 左 于 树 和 右 于 树 也 是 二 叉 查 找 树 。 


这 样 ， 一 棵 二 又 查找 树 的 所 有 元 素 节 点 都 是 有 序 的 。 在 二 又 树 的 
形态 比较 平衡 的 情况 下 ， 它 的 检索 效率 很 高 ， 有 点 类 似 于 二 分 法 检索 
有 序数 组 的 效率 。 一 般 情 况 下 ， 查 询 复 杂 度 是 与 目标 节点 到 根 节点 的 
距离 〈 即 深度 ) 有 关 的 。 人 然而， 不 断 地 添加 、 删 除 节点 ， 可 能 造成 二 
又 查找 树 形态 非常 不 平衡 ， 在 极端 情形 下 它 会 变 成 单 链表 ， 检 索 效 率 
也 就 会 变 得 低下 。 例 如 ， 在 本 节 的 例子 中 ， 依 次 将 这 10 个 数据 1、6、 
8、11、13、15、17、22、25、27 添 加 到 一 柠 普 通 的 空 二 又 查找 树 中 ， 
它 的 形态 如 图 7-6 所 示 。 


第 1 个 元 素 1 添 加 到 至 二 又 树 后 目 动 成 为 根 世 点 ， 而 后 陆续 添加 的 
元 素 正 好 以 升序 递增 ， 最 终 的 形态 必然 如 图 7-6 所 示 ， 也 就 是 相当 于 单 
链表 了 ， 由 于 树 的 深度 太 大 ， 因 此 各 种 操作 的 效率 都 会 很 低下 。 


图 7-6 普通 的 二 又 查 找 树 可 能 非常 不 平衡 


什么 是 目 平 衡 二 广 查 找 树 ? 在 不 断 地 辐 二 又 查找 树 中 添加 、 删除 
节点 时 ， 二 义 碍 找 树 自身 通过 形态 的 变换 ， 始 终 保 持 着 一 定 程度 上 的 
平衡 ， 即 为 自 平衡 二 又 碍 找 树 。 目 平衡 二 又 查找 树 只 是 一 个 概念 ， 它 
有 许多 种 不 同 的 实现 方式 ， 如 AVL 树 和 红 黑 树 。 红 黑 树 是 一 种 目 平 衡 
性 较 好 的 二 又 查找 树 ， 它 在 Linux 内 核 、C++ 的 STL 库 等 许多 场合 下 都 
作为 核心 数据 结构 使 用 。 本 和 讲述 的 ngx_rbtree_t 容 需 殉 是 一 种 由 红 壮 
树 实现 的 目 乎 衡 二 又 查找 树 。 


ngx_rbtree_t 红 黑 树 容 吉 中 的 元 素 都 是 有 序 的 ， 它 文 持 快速 的 检 
索 、 插 和 入、 删除 操作 ， 也 文 持 范 围 查 询 、 遇 有 历 等 操作 ， 有 是 一 种 应 用 场 
景 非 常 广泛 的 高 级 数据 结构 。 


7.5.2 ” 红 黑 树 的 特性 
本 广 讲 述 红 黑 树 的 特性 ， 对 于 只 想 了 解 如 何 使 用 ngx_rbtree_t 容 妖 
的 读者 ， 可 以 跳 过 本 有 。 


红 黑 树 是 指 每 个 证 点 都 党 有 颜色 属性 的 二 文 查找 树 ， 其 中 颜色 为 
红色 或 黑色 。 除 了 二 又 查找 树 的 一 般 要 求 以 外 ， 对 于 红 黑 树 还 有 如 下 
的 额外 的 特性 。 


等 性 1: 克 点 是 红色 或 黑色 。 


等 性 2: 根 世 点 是 墨色。 


特性 3: 所 有 叶子 节点 都 是 黑色 〈 时 子 是 NIL 季 点 ， 也 叫 “ 哨 


Fe 6 


特性 4， 每 个 红色 节点 的 两 个 子 节 后 都 症 黑 色 (每 个 叶子 节操 到 根 
节点 的 所 有 路 径 上 不 能 有 两 个 连续 的 红色 节点 ) 。 


特性 5: 从 任 一 节点 到 其 每 个 时 子 节 点 的 所 有 人 简单 路 径 都 包含 相同 
数目 的 黑色 节点 。 


这 些 约束 加 强 了 红 黑 树 的 关键 性 质 ， 从 根 市 点 到 叶子 节点 的 最 长 
可 能 路 径 长 度 不 大 于 最 短 可 能 路 径 的 两 倍 ， 这 样 这 个 树 大 致 上 就 是 平 
衡 的 了 。 因 为 二 叉 树 的 操作 《比如 插入 、 删 除 和 查找 某 个 值 的 最 慢 时 
间 ) 都 是 与 树 的 高 度 成 比例 的 ， 以 上 的 5 个 特性 保证 了 树 的 高 度 (最 长 
路 径 ) ， 所 以 它 完 全 不 同 于 普通 的 二 又 查找 树 。 


这 些 特性 为 什么 可 以 导致 上 述 结果 呢 ? 因为 特性 4 实际 上 决定 了 1 
个 路 径 不 能 有 两 个 毗连 的 红色 节点 ， 这 一 点 就 足够 了 。 最 短 的 可 能 路 
径 都 是 黑色 节点 ， 最 长 的 可 能 路 径 有 交替 的 红色 市 点 和 黑色 节点 。 根 
据 特 性 5 可 知 ， 所 有 最 长 的 路 径 都 有 相同 数目 的 黑色 节点 ， 这 束 表 明了 
没有 路 径 能 大 于 其 他 路 径 长 度 的 两 倍 。 


在 本 方 的 例子 中 ， 仍 然 按 照 顺序 将 这 10 个 升序 递增 的 元 素 添 加 到 
空 的 ngx_rbtree_t 红 黑 树 容器 中 ， 此 时 ， 我 们 会 发 现 根 节点 不 是 第 1 个 添 


加 的 元 素 1， 而 是 元 素 11。 实 际 上 ， 依 次 添加 元 素 1、6、8、11、13、 
15、17、22、25、27 后 ， 红 黑 树 的 形态 如 图 7-7 所 示 。 


ngx rbtree 【1 


+ngx rbtree init () 
+ngx rbtree insert () 
+ngx rbtree delete () 


HH 上。 


哨 乓 KE 及 后 


左右 子 树 


左右 子 树 
左右 子 本 
左右 子 树 


图 7-7 ngx_rbtree_t 红 黑 树 的 典型 图 示 (其 中 无 底 纹 节点 表示 红色 ， 有 
底 纹 节 点 表示 黑色 ) 


如 图 7-7 所 示 的 是 一 棵 相对 平衡 的 树 ， 它 满足 红 黑 树 的 5 个 特性 ， 最 
长 路 径 长 度 不 大 于 最 短路 径 的 2 倍 。 在 ngx_rbtree_t 红 黑 树 在 发 现 自 身 满 
足 不 了 上 述 5 个 红 墨 树 特 性 时 ， 将 会 通过 旋转 ( 同 左旋 转 或 者 同 右 旋 
转 ) 子 树 来 使 树 达到 平衡 。 这 里 不 再 讲述 红 黑 树 的 旋转 功能 ， 实 际 上 
它 非常 简单 ， 读 者 可 以 通过 ngx_rbtree_left_rotate 和 
ngx_rbtree_right_rotate 方 法 来 了 解 旋 转 功能 的 实现 。 


7.5.3” 红 黑 树 的 使 用 方法 


红 黑 树 容 絮 由 ngx_rbtree_t 结 构 体 承载 ，ngx_rbtree_t 的 成 员 和 它 相 
关 的 方法 在 图 7-7 中 可 以 看 到 ， 下 面 进行 详细 介绍 。 首 先 ， 需 要 了 解 一 
下 红 黑 树 的 太 点 结构 ， 如 图 7-8 所 示 。 


ngx rbtree node 1 


+ right 
+ parent 


+- color 


gx rbt red() 
rbt black!() 
rbt 1s red() 
rbt 1s black() 
rbt copy color() 


rbtree sentinel init() 


rbtree min() 
图 7-8” 红 黑 树 节点 的 结构 体 及 其 提供 的 方法 


ngx_rbtree_node_t 结 构 体 用 来 表示 红 黑 树 中 的 一 个 太 点 ， 它 还 提供 
了 7 个 方法 用 来 操作 和 点 。 下 面 了 解 一 下 ngx_rbtree_node_t 结 构 体 的 定 
义 ， 代 码 如 下 。 


typedef ngx_uint _t ngx_rbtree key_t; 
typedef struct ngx_rbtree node s ngx_rbtree node t; 
struct ngx_rbtree node s { 


// 无 符号 整 型 的 关键 字 


ngx_rbtree_ key_t key; 
/YY 在 子 入 


ngx_rbtree_node _t *]eft; 
// 右 子 节点 


ngx_rbtree_node_t *right; 
// 父 节点 
ngx_rbtree_node_t *parent; 


// 节点 的 颜色 ， 


0 表示 黑色 ， 


1 表示 红色 


u_char color; 
// 仅 


1 个 字 节 的 节点 数据 。 由 于 表示 的 空间 太 小 ， 所 以 一 般 很 少 使 用 


u_char data; 


}; 


ngx_rbtree_node_t 是 红 黑 树 实现 中 必须 用 到 的 数据 结构 ， 一 般 我 们 
把 它 放 到 结构 体 中 的 第 1 个 成 员 中 ， 这 样 方便 把 目 定 义 的 结构 体 强 制 转 
换 成 ngx_rbtree_node_t 类 型 。 例 如 : 


typedef struct { 
/* 一 般 都 将 


ngx_rbtree_node_t 节 点 结构 体 放 在 自 定义 数据 类 型 的 第 
1 位 ， 以 方便 类 型 的 强制 转换 


4 
ngx_rbtree_node_t node; 
ngx_uint_t num， 

} TestRBTreeNode,; 


如 果 这 里 希望 容 颖 中 元 素 的 数据 类 型 是 TestRBTreeNode， 那 么 只 
需要 在 第 1 个 成 员 中 放 上 ngx_rbtree_node_t 类 型 的 node 即 可 。 在 调用 图 7- 
7 中 ngx_rbtree_t 容 器 所 提供 的 方法 时 ， 需 要 的 参数 都 是 


ngx_rbtree_node_t 类 型 ， 这 时 将 TestRBTreeNode 类 型 的 指针 强制 转换 成 


ngx_rbtree_node_t 届 可 。 


ngx_rbtree_node_t 结 构 体 中 的 key 成 员 是 每 个 红 黑 树 节 点 的 关键 
字 ， 它 必须 是 整 型 。 红 黑 树 的 排序 主要 依据 key 成 员 (当然 ， 自 定义 
ngx_rbtree_insert_pt 方 法 后 ， 世 点 的 其 他 成 员 也 可 以 在 key 排 序 的 基础 上 
影响 红 黑 树 的 形态 )  。 在 图 7-7 所 示例 子 中 , 1、6、8、11、13、15、 
17、22、25、27 这 些 数 字 都 是 每 个 节点 的 key 关 键 子 。 


下 面 看 一 下 表示 红 黑 树 的 ngx_rbtree_t 结 构 体 是 如 何 定义 的 ， 代 码 
a 


typedef struct ngx_rbtree s ngx_rbtree_t; 
/* 为 解决 不 同 节 点 含有 相同 关键 字 的 元 素 冲 突 问 题 ， 红 黑 树 设置 J 


ngx_rbtree_insert_pt 指 针 ， 这 样 可 灵活 地 添加 冲突 元 素 


wf 

typedef void (*ngx_rbtree_insert_pt) (ngx_rbtree node t *root, 
ngx_rbtree_ node t *node, ngx_rbtree node t *sentinel); 

struct ngx_rbtree_s 


// 指向 树 的 根 节 点 。 注 意 ， 根 节点 也 是 数据 元 素 


ngx_rbtree_node t *root; 
// 指向 
NIL 哨 兵 节点 
ngx_rbtree_node_t *sentinel; 


// 表示 红 黑 树 添加 元 素 的 函数 指针 ， 它 决定 在 添加 新 节点 时 的 行为 究竟 是 末 换 还 是 新 增 


ngx_rbtree_insert_pt insert; 


在 上 段 代 码 中 ，ngx_rbtree_t 结 构 体 的 root 成 员 指 回 根 节点 ， 而 
sentinel 成 员 指 疝 哨 兵 节 点 ， 这 很 清晰 。 然 而 ，insert 成 员 作 为 一 个 
ngx_rbtree_insert_pt 类 型 的 函数 指针 ， 它 的 意义 在 哪里 呢 ? 


红 黑 树 是 一 个 通用 的 数据 结构 ， 它 的 节点 (或 者 称 为 容器 的 元 
素 ) 可 以 是 包含 基本 红 黑 树 节 点 的 任意 结构 体 。 对 于 不 同 的 结构 体 ， 
很 多 场合 下 是 允许 不 同 的 节点 拥有 相同 的 关键 字 的 (参见 图 7-8 中 的 key 

员 ， 它 作为 无 符号 整 型 数 时 表示 树 节点 的 关键 字 ) 。 例 如 ， 不 同 的 
字符 串 可 能 会 散 列 出 相同 的 关键 字 ， 这 时 它们 在 红 黑 树 中 的 关键 字 是 
相同 的 ， 然 而 它们 又 是 不 同 的 节点 ， 这 样 在 添加 时 就 不 可 以 履 盖 原 有 
同名 关键 字 节 点 ， 而 是 作为 新 插入 的 节点 存在 。 因 此 ， 在 添加 元 素 
时 ， 需 要 考虑 到 这 种 情况 。 将 添加 元 素 的 方法 抽象 出 
ngx_rbtree_insert_pt 函 数 指针 可 以 很 好 地 实现 这 一 思想 ， 用 户 也 可 以 灵 
活 地 定义 自己 的 行为 。Nginx 帮 助 用 户 实现 了 3 种 简单 行为 的 添加 市 点 
方法 ， 见 表 7-4 。 


表 7-4 ”Nginx 为 红 黑 树 已 经 实现 好 的 3 种 数据 添加 方法 


方法 名 
vold nex rbtree_ insert_value 
(ngx_ITbtree_node t *root, 
ngx rbtree node t *node, 


ngx rbtree node t *sentinel) 


void ngx_ rbtree_insert timer value 


(ngx rbtree node t *root. 
ngx rbtree_node t *node, 
ngx rbtree node t *sentinel) 


Vold ngx_ str rbtree_insert_value 
(ngx_ Ibtree node t *temp, 
ngx rbtree node t *node, 


ngx rbtree node t *sentinel) 


表 7-4 中 ngx_str_rbtree_insert_value 函 


符 是 字符 串 ， 


红 黑 树 的 第 一 排序 依据 仍然 是 


node 是 待 


root 是 红 黑 网 容 融 的 指针 ; 
添加 元 素 的 ngx_rbtree_ node t 成 员 的 指 


针 ; sentinel 是 这 棵 红 黑 树 初始 化 时 哨兵 
节点 的 指针 

root 是 红 黑 树 容 器 的 指针 ; 
添加 元 素 的 ngx ribtree node t 成 员 的 
指针 ， 它 对 应 的 关键 字 是 时 间或 者 时 间 
差 ， 可 能 是 负数 ; 是 这 棵 红 黑 树 


node 是 待 


sentinel 7 
初始 化 时 的 哨兵 节点 
root 是 红 黑 树 容 器 的 指针 
夫 加 元 素 的 ngx_str_ node t 成 员 的 指针 
( ngx_rbtree node t 类 型 会 强制 转化 为 
是 这 棵 红 


node 是 待 


ngx_str node t 类 型 ); sentinel # 
黑 树 初始 化 时 哨兵 节点 的 指针 


函数 的 应 用 场景 ; 
节点 的 key 关 键 字 ， 


执行 意 

问 红 黑 树 添加 3 和 节点， 每 个 

数据 节 点 的 关键 字 都 是 只 - 的， 

不 存 在 同 - di ep -本 二 
的 问题 


向 红 黑 树 添加 数据 节点 ， 每 个 
数据 2 点 的 关键 字 表 示 时 间或 者 
时 间 差 

向 红 黑 树 添 加 数据 节点 ， 每 个 
数据 节点 的 关键 字 呈 以 不 是 唯 
的 ， 但 它们 是 以 字符 串 作 为 唯 
的 标识 ， 存 放 在 ngx_str node t 
结构 体 的 str 成 员 中 


节点 的 标识 
第 二 排 


序 依 据 则 是 节点 的 字符 串 。 因 此 ， 使 用 ngx_str_rbtree_insert_value 时 表 
示 红 黑 树 太 点 的 结构 体 必须 是 ngx_str_node_t， 如 下 所 示 。 


typedef struct { 
ngx_rbtree_node t 
ngx_str_t 

} ngx_str_node _t,; 


node; 
str; 


同时 ， 对 于 ngx_str_node_t 广 点 ，Nginx 还 提供 了 


ngx_str_rbtree_lookup 方 法 用 于 检索 红 黑 树 市 点 


义 ， 代码 如 下 。 


VAN) 


下 面 来 看 一 下 它 的 定 


ngx_str_node t *ngx_str_rbtree lookup(ngx_rbtree t *rbtree, ngx_str_t *name, 


uint32_t hash ) ， 


其 中 ，hash 参 数 是 要 查询 节点 的 key 关 键 字 ， 而 name 是 要 查询 的 字 
符 串 (解决 不 同 字 符 串 对 应 相同 key 关 键 字 的 问题 ， 返 回 的 是 查询 到 
的 红 黑 树 市 点 结构 体 。 


天 于 红 黑 树 操 作 的 方法 见 表 7-5。 


表 7-5 ” 红 黑 树 容器 提供 的 方法 


方法 名 执行 意义 
tree 是 红 黑 树 容 需 的 指针 ; s 是 哨兵 | 初始 化 红 黑 树 ， 包 括 初始 化 根 节 
ngx_rbtree_init(tree, s. i) 入 点 的 指针 ; i 是 ngx_rbtree_insert_pt| 点 、 哨 兵 节 点 、ngx_rbtree_insert_pt 
类 型 的 节点 添加 方法 ,具体 见 表 7-4 | 节点 添加 方法 
void ngx_rbtree insert(ngx_rbtree t| tree 是 树 容 右 的 指针 ; node 是 | 向 红 黑 树 中 添加 节点 ， 该 方法 会 
*tree, ngx_rbtree_ node t *node) 需要 添加 到 红 黑 树 的 节点 指针 通过 旋转 红 黑 树 保持 树 的 平衡 
void ngx_rbtree_delete(ngx_Ibtree t| tree 是 红 黑 树 容器 的 指针 ; node 是 | 从 红 黑 树 中 删除 节点 ， 该 方法 会 
*tree, ngx_rbtree_ node t *node) 红 黑 树 中 需要 删除 的 节点 指针 通过 旋转 红 黑 树 保持 树 的 平衡 


在 初始 化 红 黑 树 时 ， 需 要 先 分 配 好 保存 红 黑 树 的 ngx_rbtree_t 结 构 
体 ， 以 及 ngx_rbtree_node_t 类 型 的 哨兵 节点 ， 并 选择 或 者 目 定 义 
ngx_rbtree_insert_pt 类 型 的 和 点 添加 男 数 。 


对 于 红 黑 树 的 每 个 节点 来 说 ， 它 们 都 具备 表 7-6 所 列 的 7 个 方法 ， 如 
果 只 是 想 了 解 如 何 使 用 红 墨 树 ， 那 么 只 需要 了 解 ngx_rbtree_min 方 法 。 


表 7-6 红 黑 树 万 点 提供 的 方法 


方法 名 执行 意义 
node 是 红 黑 树 中 ngx_rbtree node t 


ngx rbt red(node) Ef 
一 一 的 节点 指针 


设置 node 节点 的 颜色 为 红色 
de 是 红 黑 树 中 mgx_rbtree node { 


ngx rbt black(node a 
a ( ) 类 型 的 节点 指针 


设置 node 节点 的 颜色 为 黑色 
node 是 红 黑 树 中 ngx_rbtree node t| 若 node 节点 的 颜色 为 红色 ， 则 返回 非 0 


ngx Ibt ls_red(node) i Pe Se | 
Be 类 型 的 节点 指针 数值 ,否则 返回 0 


node 是 红 黑 树 中 mngx_rbtree node t| 若 nhode 节点 的 颜色 为 黑色 ， 则 返回 非 0 
类 型 的 节点 指针 数值 ， 和 否则 返回 0 


ngx rbt is_black(node) 


nl1、n2 都 是 红 黑 树 中 ngx_rbtree_ 
node t 类 型 的 节点 指针 


ngx rbt_copy_color(n1. n2) 将 n2 节点 的 颜色 复制 到 nl 节点 


ngx rbtree node t* i 
node 是 红 黑 树 中 ngx_rbtree node ft 


类 型 的 节点 指针 ; sentinel 是 这 棵 红 黑 


树 的 哨兵 节点 


ngx_rbtree_min 找到 当前 节点 及 其 子 树 中 的 最 小 节点 


(ngx_rbtree_node t *node, (按照 key 关键 字 ) 
ngx rbtree node t *sentinel) 

node 是 红 黑 树 中 ngx rbtree node t| 初始 化 哨兵 节点 ， 实际 上 就 是 将 该 节点 
类 型 的 节点 指针 颜色 置 为 黑色 


ngx rbtree_sentinel init(node) 


表 7-5 中 的 方法 大 部 分 用 于 实现 或 者 扩展 红 黑 树 的 功能 ， 如 果 只 是 
使 用 红 黑 树 ， 那 么 一 般 情况 下 只 会 使 用 ngx_rbtree_min 方 法 。 


本 市 介绍 的 方法 或 者 结构 体 的 简单 用 法 的 实现 可 参见 7.5.4 广 的 相 
天 示例 。 


7.5.4 ”使 用 红 黑 树 的 简单 例子 


本 市 以 一 个 简单 的 例子 来 说 明 如 何 使 用 红 黑 树 容 磊 。 首 先 在 栈 中 
分 配 rbtree 红 黑 树 容器 结构 体 以 及 哨兵 节点 sentinel (当然 ， 也 可 以 使 用 
内 存 池 或 者 从 进程 堆 中 分 配 ) ， 本 例 中 的 节点 完全 以 key 关 键 字 作为 每 
个 下 点 的 唯一 标识 ， 这 样 殴 可 以 采用 预 设 的 ngx_rbtree_insert_value 方 法 
了 。 最 后 可 调用 ngx_rbtree_init 方 法 初始 化 红 黑 树 ， 代 码 如 下 所 示 。 


ngx_rbtree _t rbtree,; 
ngx_rbtree_node_t sentinel; 
ngx_rbtree_init(&rbtree, &sentinel, ngx_rbtree_insert_value); 


本 例 中 树 节 点 的 结构 体 将 使 用 7.5.3 节 中 介绍 的 TestRBTreeNode 结 
构 体 ， 树 中 的 所 有 节点 都 取 自 图 7-7， 每 个 元 素 的 key 关 键 字 按 照 1、6、 
8、11、13、15、17、22、25、27 的 顺序 一 一 向 红 黑 树 中 添加 ， 代 码 如 
下 所 示 。 


TestRBTreeNode rbTreeNode[10]; 


rbTreeNode[0].num = 1; 
rbTreeNode[1].num = 6; 
rbTreeNode[2] .num = 8; 
rbTreeNode[3] .num = 11; 
rbTreeNode[4] .num = 13; 
rbTreeNode[5] .num = 15; 
rbTreeNode[6] .num = 17; 
rbTreeNode[7].num = 22， 
rbTreeNode[8] ,num = 25; 
rbTreeNode[9] .num = 27; 


for (i = 0; i < 10; i++) 


rbTreeNode[il].node.key = rbTreeNode[i].num; 
ngx_rbtree_insert(&rbtree,&rbTreeNode[i].node); 


以 这 种 顺序 添加 完 的 红 黑 树 形态 如 图 7-7 所 示 。 如 果 需 要 找 出 当前 
红 黑 树 中 最 小 的 节点 ， 可 以 调用 ngx_rbtree_min 方 法 获取 。 


ngx_rbtree node t *tmpnode = ngx_rbtree min(rbtree.root, &sentinel); 


当然 ， 参 数 中 如 果 不 使 用 根 节 点 而 是 使 用 任 一 个 节点 也 是 可 以 
的 。 下 面 来 看 一 下 如 何 检 索 1 个 市 点 ， 里 然 Nginx 对 此 并 没有 提供 预 设 
的 方法 ( 仅 对 字符 串 类 型 提供 了 ngx_str_rbtree_lookup 检 索 方法 ) ， 但 


实际 上 检索 是 非 第 侧 单 的 。 下 面 以 寻找 key 关 键 子 为 13 的 让 点 为 例 来 加 
以 说 明 。 


ngx_uint_t lookupkey = 13; 
tmpnode = rbtree,.root; 
TestRBTreeNode *lookupNode; 
while (tmpnode != &sentinel) { 
if (lookupkey != tmpnode->key) { 
// 根据 


key 关 键 字 与 当前 节点 的 大 小 比较 ， 决 定 是 检索 左 子 树 还 是 右 子 树 


tmpnode = (lookupkey < tmpnode->key) tmpnode->left : tmpnode->right; 
continue; 


} 
// 找到 了 值 为 


13 的 树 节 点 


lookupNode = (TestRBTreeNode *) tmpnode; 
break; 


从 红 黑 树 中 删除 1 个 方 点 也 是 非常 们 单 的 ， 如 把 刚刚 找到 的 值 为 13 
的 节点 从 rbtree 中 删除 ， 只 需 调 用 ngx_rbtree_delete 方 法 。 


ngx_rbtree_delete(&rbtree,&lookupNode->node ) ， 


7.5.5 ”如何 目 定 义 添 加 成 员 方法 


由 于 节点 的 key 天 键 字 必 须 是 整 型 ， 这 导致 很 多 情况 下 不 同 的 节点 
会 具有 相同 的 key 天 键 子 。 如 来 不 希 望 出 现 具有 相同 key 关 键 子 的 不 同 
市 点 在 向 红 黑 树 添 加 时 出 现 覆 盖 原 方 点 的 情况 ， 束 需要 实现 自 有 的 


ngx_rbtree_insert_pt 方 法 。 


许多 Nginx 模 块 在 使 用 红 黑 树 时 都 日 定义 了 ngx_rbtree_insert_pt 方 法 
(如 geo、 人 ecache 模 块 等 ， 本 节 以 7.5.3 节 中 介绍 过 的 
ngx_str_rbtree_insert_value 为 例 ， 来 说 明 如 何 定义 这 样 的 方法 。 先 看 一 
下 ngx_str_rbtree_insert_value 的 实现 。 代 码 如 下 。 
void 


ngx_str_rbtree insert value(ngx_rbtree node t *temp, 
ngx_rbtree_ node t *node, ngx_rbtree node t *sentinel) 


{ 
ngx_Sstr_node 不 
ngx_rbtree node t **p; 
for ( ;; ) i 


n = (ngx_str_node t *) node; 
t = (ngx_str_node t *) temp; 
// 首先 比较 


key 关 键 字 ， 红 黑 树 中 以 


key 作 为 第 一 索引 关键 字 


if (node->key != temp->key) { 
// 左 子 树 节 点 的 关键 节 小 于 右 子 树 


p = (node->key < temp->key) &temp->left : &temp->right,; 


Ne 
~ 
ls 


key 关 键 字 相同 时 ， 以 字符 串 长 度 为 第 二 索引 关键 字 


else if (n->str.len != t->str.len) { 


// 左 子 树 节 点 字符 串 的 长 度 小 于 右 子 树 


p = (n->str.len < t->str.len) &temp->left : &temp->right; 
} else { 
// key 关 键 字 相同 且 字 符 串 长 度 相 同时 ， 再 继续 比较 字符 串 内 容 


EE 


p = (ngx_memcmp(n->str.data, t->str.data, n->str.len) < 0) &temp->left 
: &temp->right; 


} 
// 如 果 当前 节点 


p 是 哨兵 和 节点， 那么 跳出 循环 准备 插入 节点 


if (*p == sentinel) { 
break; 


} 
// p 刷 点 与 要 插入 的 节点 具有 相同 的 标识 符 时 ， 必 须 履 盖 内 容 


temp = *p; 


*p = node; 
// 置 插入 节点 的 父 节 点 


node->parent = temp; 
// 左右 子 节 点 都 是 哨兵 节点 


node->left = sentinel; 
node->right = sentinel; 
/* 将 节点 颜色 置 为 红色 。 注 意 ， 红 黑 树 的 


ngx_rbtree_insert 方 法 会 在 可 能 的 旋转 操作 后 重 置 该 节点 的 颜 


*/ 
ngx_rbt_red(node); 


[Ey 


可 以 看 到 ， 该 代码 与 7.5.4 广 中 介绍 过 的 检索 节点 代码 很 相似 。 它 
所 要 处 理 的 主要 问题 束 是 当 key 关 键 子 相同 时 ， 继 续 以 何 种 数据 结构 作 
为 标准 来 确定 红 黑 树 市 点 的 唯一 性 。Nginx 中 已 经 实现 的 诸多 
ngx_rbtree_insert_pt 方 法 都 非 党 相似 的 ， 读 者 完全 可 以 参照 
ngx_str_rbtree_insert_value 方 法 来 目 定 义 红 黑 树 市 点 深 加 方法 。 


7.6 ”ngx_radix_tree_t 基 数 树 


基数 树 也 是 一 种 二 义 查 找 树 ， 然 而 它 却 不 像 红 黑 树 一 样 应 用 广泛 
(目前 官方 模块 中 仅 geo 模 块 使 用 了 基数 树 ) 。 这 是 因为 
ngx_radix_tree_t 基 数 树 有 要求 存储 的 每 个 站 点 都 必须 以 32 位 整 型 作为 区 别 
任意 两 个 证 点 的 唯一 标识 ， 而 红 黑 树 则 没有 此 要 求 。ngx_radix_tree_t 基 
数 树 与 红 黑 树 不 同 的 男 一 个 地 方 ，ngx_radix_tree_t 基 数 树 会 负责 分 配 每 
个 节 扩 占用 的 内 存 。 因 此 ， 每 个 基数 树 市 后 也 不 再 像 红 黑 树 中 那么 灵 
活 一 一 可 以 是 任意 包含 ngx_rbtree_node t 成 员 的 结构 体 。 基 数 树 的 每 个 
斑点 中 可 以 存储 的 值 只 是 1 个 指针 ， 它 指 同 实际 的 数据 。 


本 节 将 以 一 棵 完整 的 ngx_radix_tree_t 基 数 树 来 说 明基 数 树 的 原理 和 
用 法 ， 这 棵 树 的 深度 为 3， 它 包括 以 下 4 个 节点 : 0X20000000、 
0X40000000、0X80000000、0Xc0000000。 这 里 书写 成 十 六 进 制 是 为 了 
便于 理解 ， 因 为 基数 树 实际 是 按 二 进 制 位 来 建立 树 的 ， 上 面 4 个 节点 如 
采 转 换 为 十 进 制 无 符号 整 型 (也 就 是 7.6.3 节 例子 中 的 ngx_uint_t) ， 它 
们 的 值 分 别 是 536870912、1073741824、2147483648、2684354560; 如 
采 转 换 为 二 进 制 ， 它 们 的 值 分 别 为 : 
00100000000000000000000000000000、 


01000000000000000000000000000000 、 
10000000000000000000000000000000 、 


11000000000000000000000000000000。 在 图 7-9 中 ， 可 以 看 到 这 4 个 节点 
如 何 存 储 到 深度 为 3 的 基数 树 中 。 


7.6.1 ngx_radix_tree_t 基 数 树 的 原理 


基数 树 具备 二 又 查找 树 的 所 有 优点 : 基本 操作 速度 快 (如 检索 、 
插入 、 删 除 节 点 ) 、 文 持 范 围 查 询 、 文 持 志 历 操作 等 。 但 基数 树 不 像 
红 黑 树 那 样 会 通过 目 身 的 旋转 来 达到 平衡 ， 基 数 树 古 不 省 树 的 形态 是 
否 平 衡 的 ， 因 此 ， 它 搬入 节点 、 删 除 节 点 的 速度 要 比 红 黑 树 快 得 多 | 
那么 ， 基数 树 为 什么 可 以 不 管 树 的 形态 是 否 平衡 呢 ? 


红 黑 树 是 通过 不 同 节点 间 key 关 键 字 的 比较 来 决定 树 的 形态 ， 而 基 
数 树 则 不 然 ， 它 每 一 个 节点 的 key 关 键 字 已 经 决定 了 这 个 节点 处 于 树 中 
的 位 置 。 决 定 节 点 位 置 的 方法 很 简单 ， 先 将 这 个 节点 的 整 型 关键 字 转 
化 为 二 进 制 ， 从 左 向 右 数 这 32 个 位 ， 遇 到 0 时 进入 左 子 树 ， 遇 到 1 时 进 
入 右 子 树 。 因 此 ，ngx_radix_tree_t 树 的 最 大 深度 是 32。 有 时 ， 数 据 可 能 
仅 在 全 部 整 型 数 范围 的 某 一 人 小段 中 ， 为 了 减少 树 的 高 度 ， 
ngx_radix_tree_ t 义 加 入 了 掩 码 的 概念 ， 掩 码 中 为 1 的 位 节点 关键 字 中 有 
效 的 位 数 同 时 也 决定 了 树 的 有 效 高 度 。 例 如 ， 掩 码 为 
11100000000000000000000000000000 (也 就 是 0Xe0000000) 时 ， 表 示 
树 的 高 度 为 3。 如 果 1 个 节点 的 关键 字 为 0X0ffffff， 那 么 实际 上 对 于 这 


棵 基数 树 而 言 ， 它 的 节点 关键 字 相 当 于 0X00000000， 因 为 掩 码 决定 了 
仅 前 3 位 有 效 ， 并 且 它 也 只 会 放 在 树 的 第 三 层 节 点 中 。 


如 图 7-9 所 示 ，0X20000000 这 个 市 点 插 到 基数 树 后 ， 由 于 掩 码 是 
0Xe0000000， 因 此 它 决 是 了 所 有 的 节点 都 将 放 在 树 的 第 三 屋 。 下 面 结 
合 掩 码 看 看 广 点 是 如 何 根据 关键 字 来 决定 其 在 树 中 的 位 置 的 。 掩 码 中 
有 3 个 1， 将 节点 的 关键 字 0X20000000 转 化 为 二 进 制 再 取 前 3 位 为 001， 
然后 分 3 步 决定 节点 的 位 置 。 


首先 找到 根 证 点 ， 取 010 的 第 1 位 9， 表示 选择 左 于 树 。 


:第 2 位 为 0， 和 表示 再 选择 元 子 树 。 


.第 3 位 为 1， 表 示 再 选择 右 子 树 ， 此 时 的 节点 就 是 第 三 层 的 节点 ， 
这 时 会 用 它 来 存储 0X20000000 这 个 节点 。 
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用 户 自 定义 的 数据 结构 
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图 7-9 3 层 基 数 树 示意 图 


ngx_radix_tree_t 基 数 树 的 每 个 节点 由 ngx_radix_node_t 结 构 体 表 
示 ， 代 码 如 下 所 示 。 


typedef struct ngx_radix_node s ngx_radix_node_t; 
struct ngx_radix_node_s 


{ 
// 指向 右 子 树 ， 如 果 没 有 右 子 树 ， 则 值 为 
null 空 指针 


ngx_radix_node t *right; 


// 指向 左 子 树 ， 如 果 没 有 左 子 树 ， 则 值 为 


null 空 指针 


ngx_radix_node t *]left; 
// 指向 父 节点 ， 如 果 没 有 父 节 点 ， 则 (如 根 节 点 ) 值 为 


null 空 指针 


ngx_radix_node t *par 


/*value 存 全 的 是 指针 的 值 ， 和 户 定义 的 数据 结构 。 如 果 这 个 节点 还 未 使 用 ， 


value 的 值 将 是 


NGX_RADIX_NO_VALUE */ 
uintptr_t value; 


}; 


如 图 7-9 所 示 ，value 字 段 指向 用 户 自 定义 的 、 有 意义 的 数据 结构 。 
另外 ， 基 数 树 也 不 像 红 墨 树 一 样 还 有 哨兵 和 点 。 基 数 树 万 点 的 left 和 
right 都 是 有 可 能 为 nul 空 指针 的 。 


与 红 黑 树 不 同 的 是 ， 红 黑 树 容器 不 仙 贡 分 配 每 个 树 太 点 的 内 存 ， 
而 ngx_radix_tree_t 基 数 树 则 会 分 配 ngx_radix_node_t 结 构 体 ， 这 样 使 用 
ngx_radix_node_t 基 数 树 时 就 会 更 傈 单一 些 。 但 ngx_radix_node_t 基 数 树 
是 如 何 管理 这 些 ngx_radix_node_t 结 构 体 的 内 存 呢 ?下 面 来 看 一 下 
ngx_radix_node_t 容 右 的 结构 ， 代 码 如 下 。 


typedef struct { 
// 指向 根 节点 


ngx_radix_node t *root; 


// 内 存 池 ， 它 负责 给 基数 树 的 节点 分 配 内 存 


ngx_pool_t *pool; 
/* 管 理 已 经 分 配 但 暂时 未 使 用 (不 在 树 中 ) 的 节点 


free 实 际 上 是 所 有 不 在 树 中 节点 的 单 链表 


ngx_radix_node_t *free,; 
// 已 分 配 内 存 中 还 未 使 用 内 存 的 首 地 址 


char *Start ， 


// 已 分 配 内 存 中 还 未 使 用 的 内 存 大 小 


Siz 


e_t size; 
} ngx_radix_ tree _t; 


上 面 的 pool 对 象 用 来 分 配 内 存 。 每 次 删除 1 个 节点 时 ， 
ngx_radix_tree_t 基 数 树 并 不 会 释放 这 个 市 点 占用 的 内 存 ， 而 是 把 它 添 加 
到 free 单 链表 中 。 这 样 ， 在 添加 新 的 节点 时 ， 会 首先 查看 free 中 是 否 还 
有 闻 护 ， 如 琳 free 中 有 未 使 用 的 点 ， 则 会 优先 使 用 ， 如 果 没 有 ， 就 会 
再 从 pool 内 存 池 中 分 配 新 内 存 存储 节点 。 


对 于 ngx_radix_tree_{t 结 构 体 来 说 ， 仅 从 使 用 的 角度 来 看 ， 我 们 不 需 
要 了 解 pool、free、start、size 这 些 成 员 的 意义 ， 仅 了 解 如 何 使 用 root 根 
节点 即 可 。 


7.6.2 ”基数 树 的 使 用 方法 


相 比 于 红 墨 树 ，ngx_radix_tree_t 基 数 树 的 使 用 方法 要 人 商 单 许多 ， 只 
需 表 7-7 中 列 出 的 4 个 方法 即 可 简单 地 操作 基数 树 。 


表 7-7 ngx_radix_tree_t 基 数 树 提供 的 方法 


方法 名 


ngx radix tree t *ngx radix tree create 


(ngx_pool t *pool, 


ngx_int t preallocate) 


ngx int tngx radix32tree insert 
(ngx radix tree t *tree, 

uint32_t key, 

uint32_t mask., 

uintptr_t value) 


方法 名 


ngx int tngx radix32tree delete 
(ngx radix tree t *tree, 
Uint32 t key. uint32 tmask) 


uintptr t ngx radix32tree find 
(ngx radix tree t *tree, 
uint32 _t key) 


pool 是 内 存 池 指针 ，preallocate 是 预 
分 配 的 基数 树 节 点 数 ， 如 果 传 递 的 值 
为 -1， 那 么 将 会 根据 当前 操作 系统 中 

-个 页 面 的 大 小 来 预 分 配 基数 树 节 点 


tree 是 ngx_radix tree t 基 数 树 结构 
体 的 指针 ，key 是 待 插 入 节点 的 关键 
字 ，mask 为 关键 字 掩 码 (决定 key 关 
键 字 有 效 位 数 以 及 树 的 深度 )，value 
是 这 个 关键 字 对 应 数据 结构 的 指针 


tree 是 ngx_radix tree t 基数 树 结 构 
体 的 指针 ，key 是 待 删除 节点 的 关键 
字 ，mask 为 关键 字 掩 码 (决定 key 关 
键 字 有 效 位 数 ) 


tree 是 ngx_radix tree t 基数 树 结构 


体 的 指针 ，key 是 待 查 询 节 点 的 关键 字 


7.6.3 ”使 用 基数 树 的 例子 


本 市 以 图 7-9 中 的 基数 树 为 例 来 构 寺 


EradixTreei 


执行 意义 

用 来 创建 ngx radix tree t 基 
数 树 。 如 果 创 建成 功 ， 则 返回 
ngx radix tree t 结 构 体 的 指针 ; 
如 果 失 败 ， 则 返回 NULL 空 指针 

表示 向 基数 树 中 插入 1 个 节 
点 。 如 果 成 功 ， 则 返回 NGX_ 
OK ; 如 果 内 存 池 中 无 法 分 配 
足够 的 空间 ， 则 返回 NGX_ 
ERROR ; 如 果 掩 码 设 置 错 误 ， 
则 可 能 返回 NGX_BUSY 


RN 
人 
~ 


执行 意义 

表示 从 基数 树 中 删除 1 个 市 
点 。 如 果 删 除 成 功 ， 则 返回 
NGX_OK ; 如 果 删 除 失败 ， 则 
返回 NGX_ERROR 

表示 在 基数 树 中 查询 1 个 节 
点 ， 对 于 返回 的 uintptr t 类 型 
的 指针 地 址 ， 可 以 将 其 强制 转 
化 为 实际 数据 结构 的 指针 来 使 
用 。 如 果 没 有 查询 到 ， 则 会 返 
回 NGX_RADIX NO_VALUE 


这 棵 基数 树 。 目 先 ， 


使 用 ngx_radix_tree_create 方 法 创建 基数 树 ， 代 码 如 下 。 


ngx_radix_tree _t * radixTree 


ngx_radix_tree create(cf->pool, -1); 


将 预 分 配 世 点 简单 地 设置 为 -1， 
页 面 来 尽 可 能 地 分 配 基数 树 节 后 。 


这 样 pool 内 存 池 中 束 会 只 使 用 1 个 
。 接 下 来 ， 按 照 图 7-9 构 造 4 个 节点 数 


据 ， 这 里 将 它们 所 使 用 的 数据 结构 简单 地 用 无 符号 整 型 表示 ， 当 然 ， 
实际 使 用 时 可 以 是 任意 的 数据 结构 。 


ngx_uint_t testRadixValue1 = 0X20000000 
ngx_uint_t testRadixValue2 = 0x40000000 
ngx_uint_t testRadixValue3 = Ox80000000; 
ngx_uint_t testRadixValue4 = Oxa0000000; 


接 下 来 将 上 述 节 点 添加 到 radixTree 基 数 树 中 ， 注 意 ， 掩 码 是 
0xe0000000。 


int rc; 
rc = ngx_radix32tree_insert(radixTree, 

Ox20000000, 0Qxe0000000, (uintptr_t)&testRadixValuel1); 
rc = ngx_radix32tree_insert(radixTree, 

Ox40000000, QOxe0000000, (uintptr_t)&testRadixValue2); 
rc = ngx_radix32tree_insert(radixTree, 

Ox80000000, QOxe0000000, (uintptr_t)&testrRadixValue3); 
rc = ngx_radix32tree_insert(radixTree, 

0xa0000000，0xe0000000， (uintptr_t)&testRadixValue4); 


下 面 来 试 着 调用 ngx_radix32tree_find 查 询 广 点 ， 代 码 如 下 。 


ngx_uint_t* pRadixValue = (ngx_uint_t *) ngx_radix32tree _ find( radixTree, 
Ox80000000 ) ; 


注意 ， 如 采 没 有 查询 到 ， 那 么 返回 的 pRadixValue 将 会 是 


NGX RADIX NO VALUE -°° 
下 面 调 用 ngx_radix32tree_delete 删 除 1 个 和 点 ， 代 码 如 下 。 


rc = ngx_radix32tree_delete(radixTree，0xa0000000，0xe0000000 ) ; 


7.7” 文 持 通配符 的 艇 列表 


散 列 表 (也 叫 哈 希 表 ) 是 典型 的 以 空间 换 时 间 的 数据 结构 ， 在 一 
些 合理 的 假设 下 ， 对 任意 元 素 的 检索 、 插 入 速度 的 期 望 时 间 为 O(1)， 
这 种 高 效 的 方式 非常 适合 频繁 读 取 、 插 入 、 删 除 元 素 ， 以 及 对 速度 敏 
感 的 场合 。 因 此 ， 散 列表 在 以 效率 、 性 能 著称 的 Nginx 服 务 器 中 得 到 了 
广泛 的 应 用 。 


注意 ，Nginx 不 只 提供 了 基本 的 散 列 表 。Nginx 作 为 一 个 Web 服 务 
锋 ， 它 的 各 种 散 列 表 中 的 关键 字 多 以 字符 串 为 主 ， 特 别 是 URI 域 名 ， 如 
wwwi.test.com 。 这 时 一 个 基本 的 要 求 束 出现 了 ， 如 何 让 敬 列 表 文 持 通 
配 符 呢 ? 前面 在 2.4.1 节 中 介绍 了 nginx.conf 中 主机 名 称 的 配置 ， 这 里 的 
主机 域名 是 允许 以 * 作 为 通配符 的 ， 包 括 前 置 通 配 符 ， 如 *.test.com， 或 
者 后 置 通配符 ， 如 www.test.*+。Nginx 封 装 了 ngx_hash_combined_t 容 
全， 专 | 和 针对 URI 域 名 文 持 前 置 或 者 后 置 的 通配符 (不 文 持 通配符 在 域 
名 的 中 间 ) 。 


本 市 会 以 一 个 完整 的 通配符 散 列 表 为 例 来 说 明 这 个 容 旧 的 用 法 。 


7.7.1 ngx_hash_t 基 本 散 列 表 


散 列 表 和 是 根据 元 系 的 关键 码 值 而 直接 进行 访问 的 数据 结构 。 也 束 
征 况 ， 它 通过 把 关键 码 值 映射 到 表 中 一 个 位 置 来 访问 记录 ， 以 加 快 得 
找 的 速度 。 这 个 映 冉 函数 f 叫 作 散 列 方法 ， 存 放 记 杂 的 数组 叫做 散 列 
表 。 


震 结 构 中 存在 关键 季 和 K 相 等 的 记录 ， 则 必定 在 fIR) 的 存储 位 置 
上 。 由 此 ， 不 需要 比较 便 可 直接 取得 所 碍 记录 。 我 们 称 这 个 对 应 关系 f 
为 散 列 方法 ， 按 这 个 思想 建立 的 表 则 为 散 列 表 。 


对 于 不 同 的 关键 字 ， 可 能 得 到 同一 散 列 地 址 ， 即 关键 码 
key1zkey2， 而 f(key1l)=f(key2)， 这 种 现象 称 为 磁 撞 。 对 该 散 列 方法 来 
说 ， 具 有 相同 函数 值 的 关键 字 称 作 同 义 词 。 综 上 所 述 ， 根 据 散 列 方法 
H(key) 和 人 处理 磁 撞 的 方法 将 一 组 关键 字 映 象 到 一 个 有 限 的 连续 的 地 址 集 
(区 间 ) 上 ， 并 以 关键 字 在 地 址 集中 的 “ 象 ”作为 记录 在 表 中 的 存储 位 
置 ， 这 种 表 便 称 为 散 列 表 ， 这 一 映 象 过 程 称 为 散 列 造 表 或 散 列 ， 所 得 
的 存储 位 置 称 为 散 列 地 址 。 


大 对 于 关键 字 集 合 中 的 任 一 个 关键 字 ， 经 散 列 方法 映 象 到 地 址 集 
合 中 任何 一 个 地 址 的 概率 是 相等 的 ， 则 称 此 类 散 列 方法 为 均匀 散 列 方 
法 ， 这 了 吏 使 关键 字 经 过 散 列 方法 得 到 了 一 个 “随机 的 地 址 ”>， 从 而 减少 
了 础 撞 。 


1. 如 何 解 决 碰撞 问题 


如 采 得 知 散 列 表 中 的 所 有 元 素 ， 那 么 可 以 设计 出 “完美 ”的 散 列 方 
法 ， 使 得 所 有 的 元 素 经 过 f(K) 散 列 方法 运算 后 得 出 的 值 都 不 同 ， 这 样 束 
避免 了 砸 撞 问 题 。 然 而 ， 通 用 的 做 列表 是 不 可 能 预知 散 列 表 中 的 所 有 
元 了 素 的 ， 这 样 ， 通 用 的 散 列 表 都 需要 解决 碰撞 问题 。 


当 散 列表 出 现 磁 撞 时 要 如 何 解 决 呢 ? 一 般 有 两 个 向 单 的 解决 方 
法 : 分 离 链 接 法 和 开放 寻 址 法 。 


分 离 链接 法 ， 殉 是 把 散 列 到 同一 个 槽 中 的 所 有 元 素 都 放 在 艇 列表 
外 的 一 个 链表 中 ， 这 样 查询 元 素 时 ， 在 找到 这 个 槽 后 ， 还 得 志 历 链表 
才能 找到 正确 的 元 素 ， 以 此 来 解决 碰撞 问题 。 


开放 寻 址 法 ， 即 所 有 元 于 部 存放 在 散 列 表 中 ， 当 查找 一 个 元 素 
时 ， 要 检查 规则 内 的 所 有 的 表 项 〈 例 如， 连续 的 非 空 槽 或 者 整个 空间 
内 符合 散 列 方法 的 所 有 模 ) ， 直 到 找到 所 需 的 元 素 ， 或 者 最 终 发 现 元 
素 不 在 表 中 。 开 放 寻 址 法 中 没有 链表 ， 也 没有 元 素 存放 在 散 列 表 外 。 


Nginx 的 散 列 表 使 用 的 是 开放 导 址 法 。 


开放 寻 址 法 有 许多 种 实现 方式 ，Nginx 使 用 的 是 连续 非 空 槽 存储 三 
撞 元 素 的 方法 。 例 如 ， 当 插入 一 个 元 系 时 ， 可 以 按照 散 列 方法 找到 指 
定 权 ， 如 果 该 权 非 空 且 其 存储 的 元 妈 与 行 插 入 元 素 并 非 同一 元 素 ， 则 
依次 检查 其 后 连续 的 槽 ， 直 到 找到 一 个 罕 槽 来 放置 这 个 元 素 为 止 。 香 


询 元 聚 时 也 十 使 用 类 似 的 方法 ， 即 从 散 列 方法 指定 的 位 置 起 检查 连续 
的 非 空 权 中 的 元 素 。 


2.ngx_hash_t 散 列表 的 实现 


对 于 散 列 表 中 的 元 素 ，Nginx 使 用 ngx_hash_elt_t 结 构 体 来 存储 。 下 
面 看 一 下 ngx_hash_elt_t 的 成 员 ， 代 码 如 下 。 


typedef struct { 
/* 指 向 用 户 自 定义 元 素数 据 的 指针 ， 如 果 当 前 


ngx_hash_elt_t 模 为 空 ， 则 


Value 的 值 为 


© */ 
void *value; 
/* 元 素 关 键 字 的 长 度 


u_short len; 
// 元 素 关 键 字 的 首 地 址 


u_char name[1]; 
} ngx_hash_elt_t; 


每 一 个 散 列 表 楼 都 由 1 个 ngx_hash_elt_t 结 构 体 表示 ， 当 然 ， 这 个 槽 
的 大 小 与 ngx_hash_elt_t 结 构 体 的 大 小 〈 也 就 是 sizeof(ngx_hash_elt_U) 
是 不 相等 的 ， 这 是 因为 naame 成 员 只 用 于 指出 天 键 字 的 下 地 址 ， 而 天 键 
字 的 长 度 是 可 变 长 度 。 那 么 ， 一 个 槽 究竟 占用 多 大 的 空间 呢 ? 其 实 这 
是 在 初始 化 散 列 表 时 决定 的 。 基 本 的 散 列 表 由 ngx_hash_t 结 构 体 表示 ， 
如 下 所 示 。 


typedef struct { 
// 指向 散 列 表 的 首 地 址 ， 也 是 第 


1 个 槽 的 地 址 


ngx_hash_ elt t **buckets; 
// 散 列表 中 槽 的 总 数 


ngx_uint_t size; 
} ngx_hash_t， 


因此 ， 在 分 配 buckets 成 员 时 就 决定 了 每 个 权 的 长 度 (限制 了 每 个 
元 素 关 键 字 的 最 大 长 度 ， 以 及 整个 散 列 表 所 占用 的 空间 。 在 7.7.2 市 
中 将 会 介绍 Nginx 提 供 的 获 列 表 初 始 化 方法 。 


如 图 7-10 所 示 ， 散 列表 的 每 个 槽 的 首 地 址 都 是 ngx_hash_elt_t 结 构 
体 ，value 成 员 指向 用 户 有 意义 的 结构 体 ， 而 len 是 当前 这 个 槽 中 name 
(也 就 是 元 素 的 关键 字 ) 的 有 效 长 度 。ngx_hash_t 散 列表 的 buckets 指 回 
了 散 列 表 的 起 始 地 址 ， 而 size 指 出 散 列表 中 模 的 总 数 。 


ngx hash { ngx hash elt t 


+buckets 
. +value 
TSIZC + len 


Fngx hash find () +name 


用 户 结构 体 一 


value | len name value | len 


name 


Name 


共有 size 个 ngx hash_ elt t 结构 体 


图 7-10 ”ngx_hash_t 基 本 散 列 表 的 结构 示意 图 


ngx_hash_t 散 列表 还 提供 了 ngx_hash_find 方 法 用 于 查询 元 素 ， 下 面 
完 来 看 一 下 它 的 定义 。 


void *ngx_hash_find(ngx_hash_t *hash, ngx_uint_t key, u_char *name, size _t len) 


其 中 ， 参 数 hash 是 散 列 表 结 构 体 的 指针 ， 而 key 则 是 根据 散 列 方法 
算出 来 的 散 列 关键 字 ，name 和 len 则 表示 实际 关键 字 的 地 址 与 长 度 。 
ngx_hash_find 的 执行 结果 就 是 返回 散 列 表 中 关键 字 与 Iame、len 指 定 关 
键 字 完全 相同 的 槽 中 ，ngx_hash_elt_t 结 构 体 中 value 成 员 所 指向 的 用 户 
数据 。 如 果 ngx_hash_find 没 有 查询 到 这 个 元 素 ， 就 会 返回 NULL 。 


3.ngx_hash_t 的 散 列 方法 


Nginx 设 计 了 ngx_hash_key_pt 散 列 方法 指针 ， 也 束 是 说 ， 完 全 可 以 
按照 ngx_hash_key_pt 的 函数 原型 目 定义 散 列 方法 ， 如 下 所 示 。 


typedef ngx_uint_t (*ngx_hash_key_pt) (u_char *data, size t len); 


其 中 ， 传 入 的 data 古 元 素 关 键 字 的 首 地 址 ， 而 len 古 元 素 天 键 子 的 
长 度 。 可 以 把 任意 的 数据 结构 强制 转换 为 u_char* 并 传 给 
ngx_hash_key_pt 散 列 方法 ， 从 而 决定 返回 什么 样 的 艇 列 整 型 关键 码 来 
使 碰撞 率 降 低 。 


当然 ，Nginx 也 提供 了 两 种 基本 的 散 列 方法 ， 它 会 假定 关键 子 古 子 
符 串 。 如 条 关键 字 确 实 羡 字符 串 ， 那 么 可 以 使 用 表 7-8 握 供 的 散 列 方 


法 。 


表 7-8 Nginx 提 供 的 两 种 散 列 方法 


散 列 方法 意 义 
ngx uint tngx hash key(u char *data, size_t len) 使 用 BKDR 算法 将 任意 长 度 的 字符 串 映射 为 整 型 
将 字符 串 全 小 写 后 ， 青 使 用 BKDR 算法 将 任意 长 度 的 字 


ngx uint tngx hash key lc(u char *data, size tlen) 


符 串 映射 为 整 型 


这 两 种 散 列 方法 的 区 别 仅仅 在 于 ngx_hash_key_lc 将 关键 字 字 符 串 
全 小 写 后 再 调用 ngx_hash_key 来 计算 关键 码 。 


7.7.2 ”支持 通配符 的 散 列 表 


如 条 做 列表 元 系 的 关键 字 征 URI 域 名 ，Nginx 设 计 了 文 持 倘 单 通 配 
符 的 散 列 表 ngx_hash_combined t， 那 么 它 可 以 文 持 简 单 的 前 置 通配符 
或 者 后 置 通配符 。 


1. 原 理 


所 谓 文 持 通 配 符 的 散 列 表 ， 束 是 把 基本 艇 列表 中 元 素 的 关键 字 ， 
用 去 除 通 配 符 以 后 的 字符 作为 关键 字 加 入 ， 原 理 其 实 很 商 单 。 例 如 ， 
对 于 关键 字 为 “www.test.*” 这 样 带 通 配 符 的 情况 ， 直 接 建 立 一 个 专用 的 
后 置 通 配 符 散 列 表 ， 存 储 元 素 的 关键 字 为 www.test。 这 样 ， 如 果 要 检索 


www:test,cn 是 否 匹配 www.test*， 可 用 Nginx 提 供 的 专用 方法 
ngx_hash_find_wc_tail 检 索 ，ngx_hash_find_wc_tail 方 法 会 把 要 查询 的 


www.test.cn 转 化 为 wwwi.test 字 符 串 再 开始 查询 。 


同样 ， 对 于 关键 字 为 “*.test.com” 这 样 市 前 置 通 配 符 的 情况 ， 也 直 
接 建 立 了 一 个 专用 的 前 置 通配符 散 列 表 ， 存 储 元 素 的 关键 字 为 
com.test.。 如 果 我 们 要 检索 smtp.test.com 是 否 匹 配 *.test.com， 可 用 Nginx 
提供 的 专用 方法 ngx_hash_find_wc_head 检 索 ，ngx_hash_find_wc_head 
方法 会 把 要 查询 的 smtp.test.com 和 转化 为 com.test. 字 符 串 再 开始 查询 (如 
图 7-11 所 示 ) 。 


nex_hash _wildcard _1 
+ hash: nex _hash 1t 
+ value : char 


+nex_hash _ find_wcec _head () 


+nex_hash _find _wec _tal 0 


图 7-11 ngx_hash_wildcard_t 基 本 通配符 散 列表 


Nginx 封 装 了 ngx_hash_wildcard_t 结 构 体 ， 专 用 于 表示 前 置 或 者 后 
置 通配符 的 散 列 表 。 


typedef struct { 
// 基本 散 列 表 


ngx_hash_t hash; 
/* 当 使 用 这 个 


ngx_hash_wildcard _t 通 配 符 散 列表 作为 某 容 器 的 元 素 时 ， 可 以 使 用 这 个 


Value 指针 指向 用 户 数据 


void *value,; 
} ngx_hash wildcard _t; 


实际 上 ，ngx_hash_wildcard_t 只 是 对 ngx_hash_t 进 行 了 简单 的 起 
装 ， 所 加 的 value 指 针 其 用 途 也 是 多 样 化 的 。ngx_hash_wildcard_t 同 时 提 
供 了 两 种 方法 ， 分 别 用 于 查询 前 置 或 者 后 置 通配符 的 元 素 ， 见 表 7-9 。 


表 7-9 ngx_hash_wildcard_t 提 供 的 方法 


方法 原型 执行 意义 
void *ngx_ hash find we head hwc 是 散 列 表 的 指针 ,name | 将 待 查询 关键 字 name 转换 为 前 置 散 列 表 规 
(ngx hash wildcard t *hwrce, 是 待 查询 关键 字 ，len 是 待 查询 | 则 下 的 字符 串 再 递归 查询 ， 成 功 时 会 返回 找到 
u_char *name. size_t len) 关键 字 的 长 度 元 素 所 指 癌 的 用 户 数据 ， 否 则 返回 NULL 
void *ngx_ hash find we tail hwc 是 散 列 表 的 指针 ，name | 将 待 查询 关键 字 name 转换 为 后 置 散 列表 规 
(ngx_hash wildcard t *hwc， 是 待 查询 关键 字 ，len 是 待 查询 | 则 下 的 字符 串 再 递归 查询 ， 成 功 时 会 返回 找到 
u_char *name, size_t len) 关键 字 的 长 度 元 素 所 指向 的 用 户 数据 ， 和 否则 返回 NULL 


下 面 回 顾 一 下 Nginx 对 于 server_name 主 机 名 通配符 的 支持 规则 。 


首先， 选择 所 有 字符 串 完 全 匹配 的 server_name， 如 


wwwi.testweb.com 。 


其次， 选择 通配符 在 前 面 的 server_ name， 如 #.testweb.com。 


一 人 


.再 次 ， 选 择 通配符 在 后 面 的 server_name， 如 www.testweb.*。 


实际 上 ， 上 面 介绍 的 这 个 规则 束 是 Nginx 实 现 的 
ngx_hash_combined_t 通 配 符 散 列表 的 规划。 下 面 完 来 看 一 下 


ngx_hash_combined_t 的 结构 ， 代 码 如 下 。 


typedef struct { 
// 用 于 精确 匹配 的 基本 散 列 表 


ngx_hash_t hash; 
// 用 于 查询 前 置 通配符 的 散 列 表 


ngx_hash_wildcard t *wc_head; 
// 用 于 查询 后 置 通配符 的 散 列 表 


ngx_hash wildcard t *wc_ tail; 
} ngx_hash combined_t; 


如 图 7-12 所 示 ，ngx_hash_combined_t 是 由 3 个 散 列 表 所 组 成 :第 1 
个 做 列表 hash 是 普通 的 基本 散 列 表 ， 人 第 2 个 散 列 表 wc_head 所 包含 的 都 
是 市 前 置 通配符 的 元 素 ， 第 3 个 散 列 表 wc_tail 所 包含 的 都 是 市 后 置 通 配 


符 的 元 素 。 


ngx_hash _combined _+ 


+hash: ngx_hash_+ 


ea wc_head : ngx_hash_wildcard _+ 
一 +we tail: ngx_hash_wildcard _+ 
A + ngx_hash_find _combined () 


www .test.comXx' 
应 的 结构 体 


完全 匹配 的 散 列表 


Wo | Pol] | 二 ER 


六 人 


前 置 通配符 散 列 表 


区 www .test.* 对 户 Y 
加 和 


后 置 通配符 散 列表 
图 7-12 ”ngx_hash_combined_t 通 配 符 散 列 表 的 结构 示意 图 
@ 注音 前 置 通配符 散 列 表 中 元 素 的 关键 字 ， 在 把 * 通 配 符 去 掉 


后 ， 会 按照 “.” 符 号 分 隔 ， 并 以 倒序 的 方式 作为 关键 字 来 存储 元 素 。 相 
应 的 ， 在 查询 元 素 时 也 是 做 相同 处 理 。 


在 查询 元 素 时 ， 可 以 使 用 ngx_hash_combined_t 近 供 的 方法 
ngx_hash_find_combined， 下 面 先 来 看 看 它 的 定义 ( 它 的 参数 、 返 回 值 
含义 与 ngx_hash_find_wc_head 或 者 ngx_hash_find_wc_tail 方 法 相同 ) 。 


void *ngx_hash_find_combined(ngx_hash_combined_t *hash, ngx_uint_t key, u_char 
*name, size_t len); 


在 实际 向 ngx_hash_combined_t 通 配 符 散 列 表 查 询 元 素 时 ， 
ngx_hash_find_combined 方 法 的 活动 图 如 图 7-13 所 示 ， 这 是 有 严格 顺序 
的 ， 即 当 1 个 查询 关键 字 同 时 匹配 3 个 散 列表 时 ， 一 定 是 返回 普通 的 完 
全 匹配 散 列 表 的 相应 元 素 。 


在 hash 完 全 匹配 散 列 表 中 查询 元 素 


[没有 查询 到 ] 


在 wc_head 通 配 符 前 置 散 列表 中 查询 元 素 


[没有 查询 到 [已 经 查询 到 ] 


在 wc tail 通配符 后 置 散 列 表 中 查询 元 素 


[已 经 查询 到 ] 


[未 查询 到 , 返回 NULL] [已 经 查询 到 ] 


图 7-13 ”通配符 散 列 表 ngx_hash_find_combined 方 法 查询 元 素 的 活动 图 


2. 如 何 初始 化 


上 文中 对 于 普通 的 散 列 表 和 通配符 散 列 表 的 原理 和 查询 方法 做 了 
详细 的 解释 ， 实 际 上 ，Nginx 也 封装 了 完善 的 初始 化 方法 ， 以 用 于 这 些 
散 列 表 ， 并 且 Nginx 还 具备 在 初始 化 时 话 加 通配符 元 系 的 能 力 。 鉴 
此 ， 如 归功 能 较 多 ， 初 始 化 方法 的 使 用 就 会 有 些 复 杂 。 下 面 介绍 一 下 
初始 化 方法 的 使 用 。 


Nginx 专 门 提供 了 ngx_hash_init_t 结 构 体 用 于 初始 化 散 列 表 ， 代 码 
um 


typedef struct { 
// 指向 普通 的 完全 匹配 散 列 表 


ngx_hash_t *hash,; 
// 用 于 初始 化 预 添加 元 素 的 散 列 方法 


ngx_hash_key_pt key; 
// 散 列 表 中 槽 的 最 大 数目 


ngx_uint_t max_size; 


// 散 列 表 中 一 个 模 的 空间 大 小 ， 它 限制 了 每 个 散 列表 元 素 关 键 字 的 最 大 长 度 


ngx_uint_t bucket_size; 


// 散 列表 的 名 称 


char *name; 


/* 内 存 池 ， 它 分 配 散 列表 (最 多 
3 个 ， 包 括 


1 个 普通 散 列表 、 
1 个 前 置 通配符 散 列表 、 
1 个 后 置 通配符 散 列 表 ) 中 的 所 有 楼 


A 


ngx_pool t *pool,; 


/* 临 时 内 存 池 ， 它 仅 存 在 于 初始 化 散 列表 之 前 。 它 主要 用 于 分 配 一 些 临时 的 动态 数组 ， 带 通配符 的 元 素 在 
初始 化 时 需要 用 到 这 些 数组 


WA 


ngx_pool t *temp_pool; 
} ngx_hash_init_t; 


ngx_hash_init_t 结 构 体 的 用 途 只 在 于 初始 化 散 列 表 ， 到 底 初 始 化 散 
列表 时 会 预 分 配 多 少 个 槽 呢 ? 这 并 不 完全 由 max_size 成 员 决 是 的 ， 而 是 
由 在 做 初始 化 准备 时 预先 加 入 到 散 列 表 的 所 有 元 素 决 定 的 ， 包 括 这 些 
元 素 的 总 数 、 每 个 元 素 关 键 字 的 长 度 等 ， 还 包括 操作 系统 一 个 页 面 的 
大 小 。 这 个 算法 较 复杂 ， 可 以 在 ngx_hash_init_t 范 数 中 得 到 。 我 们 在 使 
用 它 时 只 需要 了 解 在 初始 化 后 每 个 ngx_hash_t 结 构 体 中 的 size 成 员 不 由 
ngx_hash_init_t 完 全 决定 即 可 。 图 7-14 显 示 了 ngx_hash_init_t 结 构 体 及 其 
支持 的 方法 。 


ngX hash init tt 
-hash 
+key 
Hmax size 
Hbucket size 
Fname 


+ pool 


ttemp pool 


Fngx hash init () 


Fngx hash wildcard init () 


图 7-14 ”ngx_hash_init_t 的 结构 及 其 提供 的 方法 


ngx_hash_init_t 的 这 两 个 方法 负责 将 ngx_hash_keys_arrays_t 中 的 相 
应 元 素 初 始 化 到 散 列 表 中 ， 表 7-10 描 述 了 这 两 个 初始 化 方法 的 用 法 。 


表 7-10 ”ngx_hash_init_t 提 供 的 两 个 初始 化 方法 


hinit 是 散 列 表 初 始 化 结构 体 的 指针 ;| 初始 化 基本 的 散 列表 。 返 回 
names 是 数组 的 首 地 址 ， 这 个 数组 中 每 个 元 |NGX_OK， 表 示 初 始 化 成 功 ， 这 
素 以 ngx_hash_key_t 作为 结构 体 ， 它 存储 着 | 时 names 数组 已 经 添加 到 hinit- 
预 添加 到 散 列表 中 的 元 素 ; nelts 是 names 数 | >hash 散 列 表 中 了 ; 返回 NGX_ 
组 的 元 素数 日 ERROR， 表 示 初 始 化 失败 


ngx int tngx hash init 
(ngx_hash init_t *hinit, 
ngx hash key_t *names, 


ngx uint t nelts) 


hinit 是 散 列 表 初 始 化 结构 体 的 指针 ; tL 符 散 列表 (前 
) 


ngx_int tngx_hash wildcard_init |names 是 数组 的 首 地 址 ， 这 个 数组 中 每 个 元 | 置 或 者 后 置 返回 NGX_ 

(ngx_hash init_t *hinit, 素 以 ngx_hash_key_t 作为 结构 体 ， 它 存储 着 |OK， 表 示 初 始 化 成 功 ， 这 时 

ngx hash key t *names, 预 添加 到 散 列 表 中 的 元 素 (这 些 元 素 的 关键 |names 数组 已 经 添加 到 hinit- 

ngx_uint tnelts) 字 要 么 含有 前 置 通配符 ， 要么 含有 后 置 通 配 | >hash 散 列 表 中 了 ; 返回 NGX_ 
符 ); nelts 是 names 数组 的 元 素数 日 ERROR， 表 示 初 始 化 失败 


表 7-10 的 两 个 方法 都 用 到 了 ngx_hash_key_t 结 构 ， 下 面 简单 地 介绍 
一 下 它 的 成 员 。 实 际 上 ， 如 来 只 是 使 用 散 列 表 ， 完 全 可 以 不 用 关心 


ngx_hash_key_t 的 结构 ， 但 为 了 更 深入 地 理解 和 应 用 还 是 简要 介绍 一 下 


Crd 


已 9 


typedef struct { 
// 元 素 关键 字 


ngx_str_t key; 
// 由 散 列 方法 算出 来 的 关键 码 


ngx_uint_t key_hash ; 
// 指向 实际 的 用 户 数据 


void *value; 
} ngx_hash_key_t; 


ngX_hash_keys_arrays_t 对 应 的 ngx_hash_add_key 方 法 负责 构造 
ngx_hash_key_t 结 构 。 下 面 来 看 一 下 ngx_hash_keys_arrays_t 结 构 体 ， 它 
不 负责 构造 散 列 表 ， 然 而 它 却 是 使 用 ngx_hash_init 或 者 
ngx_hash_wildcard_init 方 法 的 前 提 条 件 ， 换 句 话 说， 如 采 先 构造 好 了 
ngX_hash_keys_arrays_t 结 构 体 ， 束 可 以 非常 简单 地 调用 ngx_hash_init 或 
者 ngx_hash_wildcard_init 方 法 来 创建 文 持 通配符 的 散 列 表 了 。 


typedef struct { 
/* 下 面 的 


keys_hash、 


dns_wc_head_hash、 


dns_wc_tail_hash 都 是 简易 散 列 表 ， 而 


hsize 指 明了 散 列表 的 模 个 数 ， 其 简易 散 列 方法 也 需要 对 
hsize 求 余 


人 

ngx_uint_t hsize,; 

/* 内 存 池 ， 用 于 分 配 永久 性 内 存 ， 到 目前 的 
Nginx 版 本 为 止 ， 该 


poo1 成 员 没 有 任何 意义 


yA 
ngx_pool _t *pool,; 
// 临时 内 存 池 ， 下 面 的 动态 数组 需要 的 内 存 都 


temp_pool 内 存 池 分 配 


ngx_pool t *temp_pool; 
// 用 动态 数组 以 


ngx_hash_key_t 结 构 体 保存 着 不 含有 通配符 关键 字 的 元 素 


ngx_array_t keys,; 


/* 一 个 极其 简易 的 散 列表 ， 它 以 数组 的 形式 保存 着 


hsize 个 元 素 ， 每 个 元 素 都 是 
ngx_array_t 动 态 数组 。 在 用 户 添加 的 元 素 过 程 中 ， 会 根据 关键 码 将 用 户 的 
ngx_str_t 类 型 的 关键 字 添 加 到 


ngx_array_t 动 态 数组 中 。 这 里 所 有 的 用 户 元 素 的 关键 字 都 不 可 以 带 通配符 ， 表 示 精 确 匹 配 


* 

/ 
ngx_array_t *keys_hash,; 
/* 用 动态 数组 以 


ngx_hash_key_t 结 构 体 保存 着 含有 户 


置 通配符 关键 字 的 元 素 生 成 的 中 间 关 键 字 


i 


ngx_array_t dns_wc_head; 
/* 一 个 极其 简易 的 散 列 表 ， 它 以 数组 的 形式 保存 着 
hsize 个 元 素 ， 每 个 元 素 都 是 
ngx_array_t 动 态 数组 。 在 用 户 添加 元 素 过 程 中 ， 会 根据 关键 码 将 用 户 的 
ngx_str_t 类 型 的 关键 字 添 加 到 
ngx_array_t 动 态 数组 中 。 这 里 所 有 的 用 户 元 素 的 关键 字 都 带 前 置 通配符 


*/ 


ngx_array_t *dns_ wc_head_hash; 
/* 用 动态 数组 以 


ngx_hash_key_t 结 构 体 保存 着 含有 后 置 通配符 关键 字 的 元 素 生成 的 中 间 关 键 字 


*/ 

ngx_array_t dns wc_tail; 

/* 一 个 极其 简易 的 散 列 表 ， 它 以 数组 的 形式 保存 着 
hsize 个 元 素 ， 每 个 元 素 都 是 


ngx_array_t 动 态 数 组 。 在 用 户 添加 元 素 过 程 中 ， 会 根据 关键 码 将 用 户 的 
ngx_str_t 类 型 的 关键 字 添 加 到 
ngx_array_t 动 态 数组 中 。 这 里 所 有 的 用 户 元 素 的 关键 字 都 带 后 置 通配符 


*/ 


ngx_array_t *dns wc_tail hash; 
} ngx_hash_keys_arrays_t; 


如 图 7-15 所 示 ，ngx_hash_keys_arrays_t 中 的 3 个 动态 数组 容器 
keys、dns_wc_head、dns_wc_tail 会 以 ngx_hash_key_t 结 构 体 作为 元 素 类 
型 ,分别 保 存 完 全 匹配 关键 字 、 带 前 置 通配符 的 关键 字 、 带 后 置 通 配 

符 的 关键 字 。 同 时 ，ngx_hash_keys_arrays_t 建 立 了 3 个 简易 的 散 列 表 
keys_hash、dns_wc_head_hash、dns_wc_tail_hash， 这 3 个 散 列 表 用 于 快 
速 问 上述 3 个 动态 数组 容 圳 中 插入 元 素 。 


二 key 
十 key_hash 
+value 


Www .test.com 关 键 


*. test .com 关键 字 


www .test.* 关键 字 


ngx hash keys arrays _t 


dns _wc head _hash 
一 一 一 em 
+dns_wc tail hash 
+ngx_hash keys array _init () 


A 2 
7 


ngx_str t 组 成 的 动态 数组 


Wl | 因 
ngx_str t 组 成 的 动态 数组 
i | 


在 上 面 3 个 散 列表 中 ， 按 
照 每 个 关键 字 的 散 列 码 指 
定 的 档 存 放 ngx_str_t 组 成 
的 动态 数组 ， 每 个 ngx_str tt 
指向 真正 的 关键 字 的 值 


ngx_str_t 组 成 的 动态 效 组 


EE 


e 
hash value 


ngx hash key t 
Co 
ngx hash key t 


key . 


ngx hash key t 


在 这 3 个 动态 数组 的 
ngx_hash_key_t 元 素 中 ， 
key 指 向 关键 字 的 值 ， 
key_hash 是 计算 出 的 散 列 
码 ，value 指 向 实际 的 用 
户 数据 


图 7-15 ”ngx_hash_keys_arrays_t 中 动态 数组 、 散 列表 成 员 的 简易 示意 图 


为 什么 要 设立 


这 3 个 简易 散 列 表 呢 ?如 果 没 有 这 3 个 散 列 表 ， 在 向 


keys、dns_wc_head、dns_wc tail 动 态 数组 添加 元 素 时 ， 为 了 避免 出 现 


相同 关键 字 的 元 素 ， 每 添加 一 个 关键 字 元 素 都 需 


所 历 整 个 数组 。 有 


了 keys_hash、dns_wc_head_hash、dns_wc _tail_hash 这 3 个 人 徐 易 散 列表 
后 ， 每 回 keys、dns_wc_head、dns_wc_tail 动 态 数组 添加 1 个 元 系 时 ， 了 就 
用 这 个 元 素 的 天 键 字 计 算出 散 列 码 ， 然 后 按照 散 列 码 在 keys_hash、 
dns_wc_head_hash、dns_wc_tail_hash 散 列表 中 的 相应 位 置 建立 
ngx_array_t 动 态 数组 ， 动 态 数 组 中 的 每 个 元 素 是 ngx_str_ t， 它 指 癌 关 键 
字 字 符 串 。 这 样 ， 再 次 添加 同名 关键 字 时 ， 就 可 以 由 散 列 码 立 刻 获 得 
经 添加 的 天 键 字 ， 以 此 来 判定 是 否 合法 或 者 进行 元 素 合并 操作。 


已 


ngx_hash_keys_arrays_t 之 所 以 设计 得 比较 复杂 ， 是 为 了 让 keys、 
dns_wc_head、dns_wc _tail 这 3 个 动态 数组 中 存放 的 都 是 有 效 的 元 素 。 表 
7-11 介 绍 了 ngx_hash_keys_arrays_t 提 供 的 两 个 方法 。 


日 六 
表 7-11 ngx_hash_keys_arrays_t 提 供 的 两 个 方法 
方法 名 执行 意义 
ha 是 要 初始 化 的 ngx_hash keys _arrays t| 初始 化 ngx hash keys arrays_t 
ngx int tngx hash keys_array init | 结构 体 指针 ; type 取 值 范 轩 有 两 个 ， 其 中 | 结构 体 ， 在 回 ha 加 入 成 员 前 必 


(ngx_hash keys arrays_t *ha， NGX_HASH_SMALL 表示 待 初始 化 的 元 | 须 先 调用 该 方法 。 返 回 NGX_ 
ngx_uint t type) 素 较 少 ， 而 NGX_HASH_LARGE 表示 待 |OK， 表 示 成 功 ， 返 回 NGX_ 


初始 化 的 元 素 较 多 ERROR ， 表 示 失 败 


ha 是 要 初始 化 的 ngx_hash keys_arrays 
t 结 构 体 指针 ; key 是 添加 元 素 的 关键 字 ; 


value 是 key 关键 字 对 应 的 用 户 数据 的 指 


ngx_int t ngx hash add key 针 ; flags 的 取 值 有 3 种 : NGX HASH_ ; 了 天 
> ea 回 ha 中 添加 1 个 元 素 。 返 
(ngx hash keys arrays_t *ha. WILDCARD KEY 表示 需要 处 理 通配符 ; 4 
ww | 回 NGX _ OK， 表示 成 功 ， 返 回 
ngx_str t *key, void *value, NGX HASH READONLY KEY 表示 关键 


NE NGX_ERROR， 表 示 失 由 
ngx_uint t flags) 字 不 可 以 做 更 改 (也 就 是 不 可 以 通过 全 小 本 家 用 


写 关键 字 来 获取 散 列 码 ); 其 他 值 表示 既 不 
处 理 通 配 符 ， 又 允许 通过 把 关键 字 全 小 写 
来 获取 散 列 码 


ngx_hash_keys_array_init 方 法 的 type 参 数 将 会 决定 
ngx_hash_keys_arrays_t 中 3 个 简易 散 列 表 的 大 小 。 当 type 为 
NGX_HASH_SMALL 时 ， 这 3 个 艇 列表 中 槽 的 数目 为 107 个 ;， 当 type 为 
NGX_HASH_LARGE 时 ， 这 3 个 散 列 表 中 槽 的 数目 为 10007 个 。 


在 使 用 ngx_hash_keys_array_init 初 始 化 ngx_hash_keys_arrays_t 结 构 
体 后 ， 就 可 以 调用 ngx_hash_add_key 方 法 向 其 加 入 散 列表 元 素 了 。 当 添 
加 元 素 成 功 后 ， 再 调用 ngx_hash_init_t 提 供 的 两 个 初始 化 方法 来 创建 散 
列表 ， 这 样 得 到 的 散 列 表 就 是 完全 可 用 的 容器 了 


7.7.3 ”市 通配符 艇 列表 的 使 用 例子 


散 列 表 元 素 ngx_hash_elt_t 中 value 指 针 指 向 的 数据 结构 为 下 面 定义 
的 TestWildcardHash-Node 结 构 体 ， 代 码 如 下 。 


typedef struct { 
// 用 于 散 列 表 中 的 关键 字 


ngx_str_t servername; 
// 这 个 成 员 仅 是 为 了 方便 区 别 而 已 


ngx_int_t Sed， 
} TestwildcardHashNode 


每 个 散 列表 元 素 的 关键 字 是 servername 字 符 串 。 下 面 先 定义 
ngx_hash_init_t 和 ngx_hash_keys_arrays_t 变 量 ， 为 初始 化 散 列 表 做 准 
备 ， 代 码 如 下 。 


// 定义 用 于 初始 化 散 列表 的 结构 体 


ngx_hash_init_t hash 
/* ngx_hash_keys_arrays_t 用 于 预先 向 散 列 表 中 添加 元 素 ， 这 里 的 元 素 支 持 带 通配符 


*/ 
ngx_hash_keys_arrays_t ha; 
// 支持 通配符 的 散 列 表 


ngx_hash_combined_t combinedHash,; 
ngx_memzero(&ha, sizeof(ngx_hash_ keys_arrays_t)); 


combinedHash 是 我 们 定义 的 用 于 指 癌 散 列表 的 变量 ， 它 包括 指 癌 3 
个 散 列 表 的 指针 ， 下 面 会 依次 给 这 3 个 散 列 表 指 针 赋 值 。 


// 临时 内 存 池 只 是 月 


于 初始 化 通配符 散 列表 ， 在 初始 化 完成 后 就 可 以 销毁 掉 


[ma 


ha.temp_pool = ngx_create_poo1(16384，cf->1og) ; 
if (ha.temp_pool == NULL) { 

return NGX_ERROR; 
} 


/* 由 于 这 个 例子 是 在 


ngx_http_mytest_postconf 画 数 中 的 ， 所 以 就 用 了 


ngx_conf_t 类 型 的 


cf 下 的 内 存 池 作为 散 列表 的 内 存 池 


ha.pool = cf->pool; 


调用 ngx_hash_keys_array_init 方 法 来 初始 化 ha， 为 下 一 步 同 ha 中 加 
入 散 列表 元 素 做 好 和 准备， 代码 如 下 。 


if (ngx_hash_keys_array_init(&ha，NGX_HASH_LARGE) != NGX_OK) { 
return NGX_ERROR 
站 


本 世 按 照 图 7-12 和 图 7-15 中 的 例子 建立 3 个 数据 ， 并 且 会 覆盖 7.7 他 
中 介绍 的 散 列 表 内 容 。 我 们 建立 的 testHashNode[3] 这 3 个 
TestWildcardHashNode 类 型 的 结构 体 ， 分 别 表示 可 以 用 前 置 通配符 匹配 
的 散 列 表 元 素 、 可 以 用 后 置 通配符 匹配 的 散 列 表 元 素 、 需 要 完全 匹配 
的 散 列 表 元 素 。 


TestwildcardHashNode testHashNode[3]; 

testHashNode[0].servername.len = ngx_strlen("*.test.com"); 
testHashNode[0].servername .data = ngx_pcalloc(cf->pool, ngx_strlen("*.test.com")); 
ngx_memcpy(testHashNode[0].servername.data,"*.test.com",ngx_strlen("*.test.com")); 
testHashNode[1].servername.len = ngx_strlen("www.test.*"); 
testHashNode[1].servername.data = ngx_pcalloc(cf->pool, ngx_strlen("www.test.*")); 
ngx_memcpy(testHashNode[1].servername.data, "www.test.*",ngx_strlen("www.test.*")); 
testHashNode[2].servername.len = ngx_strlen("www.test.com"); 
testHashNode[2].servername.data = ngx_pcalloc(cf->pool, 
ngx_strlen("www.test,.com")); 
ngx_memcpy(testHashNode[2].servername.data, "www.test,com'" ,ngx_strlen("www,test.com 
")); 


忆 


下 面 通过 调用 ngx_hash_add_key 方 法 将 testHashNode[3] 这 3 个 成 员 
添加 到 ha 中 。 


for (i = 0; i < 3; i++) 


{ 
testHashNode[i].seq = 工 
ngx_hash_add_key(&ha, &testHashNode[i].servername, 
&testHashNode[I],NGX_HASH_WILDCARD_KEY ) ， 

} 


注意 ， 在 上 面 添加 散 列 表 元 素 时 ，flag 设 置 为 
NGX_HASH_WILDCARD_KEY， 这 样 才 会 处 理 带 通配符 的 关键 字 


oO 


在 调用 ngx_hash_init_t 的 初始 化 函数 前 ， 先 得 设置 好 
ngx_hash_init_t 中 的 成 员 ， 如 槽 的 大 小 、 散 列 方法 等 ， 如 下 所 示 。 


hash.key = ngx_hash_key_lc; 
hash.max_size = 100; 
hash.bucket_size = 48; 

hash.name = "test_server_name_hash",， 
hash.pool = cf->pool， 


ha 的 keys 动 态 数 组 中 存放 的 是 需要 完全 匹配 的 关键 字 ， 如 果 keys 数 
组 不 为 至， 那么 开始 初始 化 第 1 个 散 列 表 ， 代 码 如 下 。 


if (ha.keys.nelts) { 
/* 需 要 显 式 地 把 


ngx_hash_init_t 中 的 


hash 指 针 指 向 


combinedHash 中 的 完全 匹配 散 列 表 


*/ 
hash.hash = &combinedHash.hash 
// 初始 化 完全 匹配 散 列 表 时 不 会 使 用 到 临时 内 存 池 


hash.temp_pool = NULL; 
/* 将 


keys 动 态 数 组 直接 传 给 


ngx_hash_init 方 法 即 可 ， 


ngx_hash_init_t 中 的 


l 


hash 指 针 就 是 初始 化 成 功 的 散 列表 


A 
if (ngx_hash_ init(&hash, ha.keys.elts, ha.keys.nelts) != NGX_OK) 


return NGX_ERROR; 


下 面 继续 初始 化 前 置 通配符 散 列 表 ， 代 码 如 下 。 


if (ha.dns wc_head.nelts) { 
hash.hash = NULL; 
// 注意 ， 


ngx_hash_wildcard_init 方 法 需要 使 


各 时 内 存 池 


hash.temp_pool = ha.temp_pool; 

If (ngx_hash wildcard init(&hash, ha.dns wc_ head.elts, 
ha.dns_wc_head.nelts)!= NGX_OK) 

{ 


return NGX_ERROR; 


/* ngx_hash_init_t 中 的 
hash 指 针 是 


ngx_hash_wildcard_init 初 始 化 成 功 的 散 列 表 ， 需 要 将 它 赋 到 


combinedHash .wc_head 前 置 通配符 散 列 表 指 针 中 


*/ 


} 


combinedHash.wc_head = (ngx_hash wildcard t *) hash.hash; 


下 面 继续 初始 化 后 置 通配符 散 列 表 ， 代 码 如 下 。 


If (ha.dns wc_tail.nelts) { 
hash.hash = NULL; 
// 注意 ， 


备 时 内 存 池 


ngx_hash_wildcard_init 方 法 需要 使 用 


hash.temp_pool = ha.temp_pool; 
if (ngx_hash wildcard init(&hash, ha.dns wc _ tail.elts, 
ha.dns_wc_tail.nelts)!= NGX_OK) 


return NGX_ERROR; 


} 
/* ngx_hash_init_t 中 的 


hash 指 针 是 


ngx_hash_wildcard_init 初 始 化 成 功 的 散 列 表 ， 需 要 将 它 赋 到 


combinedHash,wc_tail 后 置 通配符 散 列表 指针 中 


7 


} 


combinedHash.wc_tail = (ngx_hash wildcard t *) hash.hash; 


到 此 ， 临 时 内 存 池 已 经 没有 存在 的 意义 了 ， 也 就 是 说 ， 
ngX_hash_keys_arrays_t 中 的 这 些 数组 、 人 简易 散 列 表 都 可 以 销毁 了 “。 这 
时 ， 只 需要 简单 地 把 temp_pool 内 存 池 销毁 就 可 以 了 ， 代 码 如 下 。 


ngx_destroy_pool(ha.temp_pool) ， 


下 面 检查 一 下 散 列 表 是 否 工 作 正 常 。 首 和 完 ， 查 询 天 键 字 
wwwi.test.org， 实 际 上 ， 它 应 该 匹配 后 置 通配符 散 列 表 中 的 元 于 
www.test.*， 代 码 如 下 。 


// 首先 定义 待 查 询 的 关键 字 字 符 串 


findServer 
ngx_str_t findServer,; 
findServer.len = ngx_strlen("www.test,.org"); 


/* 为 什么 必须 要 在 内 存 池 中 分 配 空间 以 保存 关键 字 呢 ?因为 我 们 使 用 的 散 列 方法 是 


ngx_hash_key_lc， 它 会 试 着 把 关键 字 全 小 写 


ff 
findServer.data = ngx_pcalloc(cf->pool, ngx_strlen("www.test.org")); 

ngx_memcpy(findServer.data, "www.test.org",ngx_strlen("www.test.org")); 
/* ngx_hash_find_combined 方 法 会 查找 出 


www. test .* 对 应 的 散 列表 元 素 ， 返 回 其 指向 的 用 户 数据 


ngx_hash_find_combined， 也 就 是 


testHashNode[1]*/ 
TestwildcardHashNode* findHashNode = 
ngx_hash_find_ combined(&combinedHash, 
ngx_hash_key_lc(findServer.data, findserver.1len), 
findServer.data, findSserver.1en); 


如 有 果 没 有 查询 到 的 话 ， 那 么 findHashNode 值 为 NULL 空 指针 。 


下 面试 着 查询 www.testcom， 实 际 上 ，testHashNode[0]、 
testHashNode[1] 、testHashNode[2] 这 3 个 布点 都 是 匹配 的 ， 因 为 
#test.com、Wwww.test,*、Wwwwtest.com 明 显 都 是 匹配 的 。 但 按照 完全 匹 
配 最 优先 的 规则 ，ngx_hash_find_combined 方 法 会 返回 testHashNode[2] 
的 地 址 ， 也 就 是 www.test.com 对 应 的 元 系 。 


findServer .len = ngx_strJen("www,test,com") ; 

findServer .data = ngx_pcalloc(cf->pool, ngx_strlen("www.test,.com")); 

ngx_memcpy(findServer.data, "www.test.com",ngx_strlen("www.test.com")); 

findHashNode = ngx_hash_find_combined(&combinedHash, 
ngx_hash_key_lc(findServer.data, findSserver.1len), 
findServer.data, findServer.1en); 


下 面 测试 一 下 后 置 通配符 散 列 表 。 如 采 查 询 的 关键 字 
是 “smtp.testcom”， 那 么 查询 到 的 应 该 是 关键 字 为 *.test.com 的 元 素 


testHashNode[0]。 


findServer. len = ngx_strlen("smtp.test.com"); 

findServer.data = ngx_pcalloc(cf->pool, ngx_strlen("smtp.test.com")); 

ngx_memcpy(findServer.data,"smtp.test.com",ngx_strlen("smtp.test.com")); 

findHashNode = ngx_hash_find_combined(&combinedHash, 
ngx_hash_key_lc(findServer.data, findSserver.1len), 
findServer.data, findServer.1en); 
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本 章 介 绍 了 Nginx 的 常用 容器 ， 这 对 我 们 开发 复杂 的 Nginx 模 块 非 
常 有 意义 。 当 我 们 需要 用 到 高 级 的 数据 结构 时 ， 选 择 手 段 是 非常 少 
的 ， 因 为 makefile 都 是 由 Nginx 的 configure 脚 本 生成 的 ， 如 果 想 加 入 第 
三 方 中 间 件 将 会 市 来 许多 风险 ， 而 上 自己 重新 实现 容 帮 的 代价 又 非常 
高 ， 这 时 使 用 Nginx 提 供 的 通用 容 右 就 很 有 意义 了 。 然 而 ，Nginx 封 装 
的 这 几 种 容器 在 使 用 上 各 不 相同 ， 有 些 令 人 头疼 ， 而 且 代 码 注释 几乎 
没有 ， 束 造成 了 使 用 这 几 个 容器 很 困难 ， 还 容易 出 错 。 通 过 阅读 本 章 
内 容 ， 相 信 读 者 不 再 会 为 这 些 容器 的 使 用 而 烦恼 了 ， 而 且 也 应 该 具备 
轻松 修改 、 升 级 这 些 容 强 的 能 力 了 。 了 解 本 章 介绍 的 容器 是 今后 深入 


开发 Nginx 的 基础 。 
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第 8 章 “Nginx 基 础 架构 


在 本 书 的 第 二 部 分 ， 我 们 已 经 学 习 了 如 何 开 发 HTTP 模块 ， 这 使 得 
我 们 可 以 实现 高 性 能 、 定 制 化 的 Web 服 务 器 功能 。 不 过 ，Nginx 自 身 是 
高 度 模块 化 设计 的 ， 它 给 予 了 每 一 个 基本 的 Nginx 模 块 足够 的 灵活 性 ， 
也 就 是 说 ， 我 们 不 仅仅 能 开发 HTTP 模 块 ， 还 可 以 方便 地 开发 任何 基于 
TCP 的 模块 ， 甚 至 可 以 定义 一 类 新 的 Nginx 模 块 ， 就 像 HTTP 模 块 、 
mail 模 块 曾经 做 过 的 那样 。 任 何 我 们 能 想到 的 功能 ， 只 要 符合 本 章 中 
描述 的 Nginx 设 计 原则 ， 都 可 以 以 模块 的 方式 添加 到 Nginx 服 务 中 ， 从 
而 提供 强大 的 Web 服 务 器 。 


男 外 ，Nginx 的 BSD 许 可 证 足够 开放 和 上 自由， 因此 ， 当 Nginx 的 一 
些 通用 功能 与 要 求 不 符合 我 们 的 想象 时 ， 还 可 以 尝试 着 直接 更 改 它 的 
官方 代码 ， 从 而 更 直接 地 达到 业务 要 求 。 同 时 ，Nginx 也 处 于 快速 的 发 
展 中 ， 代 码 中 免不了 会 有 一 些 Bug， 如 果 我 们 对 Nginx 的 架构 有 充分 的 
了 解 ， 也 可 以 积极 地 协助 完善 Nginx 框 架 代 码 。 


以 上 这 些 方向 ， 都 需要 我 们 在 整体 上 对 Nginx 的 架构 有 清晰 的 认 
识 。 因 此 ， 本 章 的 写作 目的 只 有 两 个 : 


:对 Nginx 的 设计 思路 做 一 个 概括 性 的 说 明 ， 帮 助 读者 了 解 Nginx 的 
设计 原则 ( 见 8.1 节 和 8.2 节 ) 。 


:将 从 具体 的 框架 代码 入 手 ， 讨 论 Nginx 如 何 启 动 、 运 行 和 退出 ， 
这 里 会 涉及 具体 实现 细节 ， 如 master 进 程 如 何 管理 worker 进 程 、 每 个 模 
块 是 如 何 加 载 到 进程 中 的 等 ( 见 8.3 节 ~8.6 世 ) 。 


通过 阅读 本 章 内 容 ， 我 们 将 会 对 Nginx 这 个 Web 服 务 器 有 一 个 全 面 
的 认识 ， 并 对 日 益 增 长 的 各 种 Nginx 模 块 与 核心 模块 的 关系 有 一 个 大 概 
的 了 解 。 另 外 ， 本 章 内 容 将 为 下 一 章 (事件 模块 ) 以 及 后 续 章 万 中 
HTTP 模 块 的 学 习 打 下 基础 。 


8.1 _ Web 服务 需 设 计 中 的 关键 约束 


Nginx 是 一 个 功能 堪 比 Apache 的 Web 服 务 器 。 然 而 ， 在 设计 时 ， 为 
了 使 其 能 够 适应 互联 网 用 户 的 高 速 增 长 及 其 市 来 的 多 样 化 需求 ， 在 基 
本 的 功能 需求 之 外 ， 还 有 许多 设计 约束 。Nginx 作 为 Web 服 务 器 受制 于 
Web 传 输 协 议 目 身 的 约束 ， 另 外 ， 下 面 将 说 明 的 7 个 关注 点 也 是 Nginx 
架构 设计 中 的 关键 约束 ， 本 划 会 分 市 简要 介绍 这 些 概 念 。 在 8.2 节 中 ， 
我 们 将 带 着 这 些 问题 再 看 一 下 Nginx 是 如 何 有 效 提升 这 些 关 注 点 属性 
的 。 


性 能 是 Nginx 的 根本 ， 如 采 性 能 无 法 超越 Apache， 那 么 它 也 惑 没 
有 存在 的 意义 了 。 这 里 所 说 的 性 能 主体 是 Web 服务 右 ， 因 此 ， 性 能 这 
个 概念 主要 是 从 网 络 角 度 出 发 的 ， 它 包含 以 下 3 个 概念 。 


(1) 网 络 性 能 


这 里 的 网 络 性 能 不 是 针对 一 个 用 户 而 言 的 ， 而 是 针对 Nginx 服 务 而 
言 的 。 网 络 性 能 是 指 在 不 同 负 载 下 ，Web 服 务 在 网 络 通信 上 的 吞吐 
° 而 市 宽 这 个 概念 ， 束 是 指 在 特定 的 网 络 连 接 上 可 以 达到 的 最 大 厂 
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吐 量 。 因 此 ， 网 络 性 能 肯定 会 受制 于 市 宽 ， 当 然 更 多 的 是 受制 于 Web 
服务 的 软件 架构 。 


在 大 多 数 场景 下 ， 随 着 服务 右上 并 发 连接 数 的 增加 ， 网 络 性 能 都 
会 有 所 下 降 。 目 前 ， 我 们 在 谈 网 络 性 能 时 ， 更 多 的 是 对 应 于 高 并 发 场 
景 。 例 如 ， 在 几 万 或 者 几 十 万 并 发 连接 下 ， 要 求 我 们 的 服务 右 仍 然 可 
以 保持 较 高 的 网 络 吞 吐 量 ， 而 不 是 当 并 发 连接 数 达 到 一 定数 量 时 ， 服 
务 器 的 CPU 等 资源 大 都 浪费 在 进程 间 切 换 、 休 有 眠 、 等 行 等 其 他 活动 
上 ， 寻 致 吞吐 量 大 幅 下 降 。 


(2) 单 次 请 求 的 延迟 性 


单 次 请 求 的 延迟 性 与 上 面 说 的 网 络 性 能 的 差别 很 明显 ， 这 里 只 是 
针对 一 个 用 户 而 言 的 。 对 于 Web 服 务 器 ， 延 迟 性 就 区 
收 到 一 个 用 户 请 求 直至 返回 啊 应 之 间 持 续 的 时 间 。 
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服务 硕 在 低 并 发 和 高 并 发 连接 数量 下 ， 单 个 请 求 的 平均 延迟 时 间 
肯定 是 不 同 的 。Nginx 在 设计 时 更 应 该 考虑 的 是 在 高 并 发 下 如 何 保持 平 
均 时 延性 ， 使 其 不 要 上 升 得 太 快 。 


(3) 网 络 效率 


网 络 效率 很 好 理解 ， 束 是 使 用 网 络 的 效率 。 例 如 ， 使 用 长 连接 
(keepalive) 代替 短 连 接 以 减少 建立 、 关 闭 连 接 带 来 的 网 络 交 互 ， 使 


用 压缩 算法 来 增加 相同 吞吐 量 下 的 信息 携带 量 ， 使 用 缓存 来 减少 网 络 
交互 次 数 等 ， 它 们 都 可 以 提高 网 络 效 率 。 


2. 可 伸缩 性 


可 伸缩 性 指 染 构 可 以 通过 添加 组 件 来 提升 服务 ， 或 者 允许 组 件 之 
间 具 有 交互 功能 。 一 般 可 以 通过 简化 组 件 、 降 低 组 件 间 的 糊 合 度 、 将 
服务 分 散 到 许多 组 件 等 方法 来 改善 可 伸缩 性 。 可 伸缩 性 受到 组 件 间 的 
交互 频率 ， 以 及 组 件 对 一 个 请 求 是 使 用 同步 还 是 异步 的 方式 来 处 理 等 
条 件 制 何 * 


3. 人 简单 性 


人 简单 性 通常 指 组 件 的 简单 程度 ， 每 个 组 件 越位 单 ， 束 会 越 容易 理 
解 和 实现 ， 也 就 越 容易 被 验证 (被 测试 ) 。 一 般 ， 我 们 通过 分 离 关 注 
点 原则 来 设计 组 件 ， 对 于 束 体 她 构 来 说 ， 通 彰 使 用 通用 性 原则 ， 统 一 
组 件 的 接口 ， 这 样 束 减少 了 架构 中 的 变数 。 


4. 可 修改 性 


人 简单 来 讲 ， 可 修改 性 就 是 在 当前 染 构 下 对 于 系统 功能 做 出 修改 的 
难 易 程度 ， 对 于 Web 服 务 器 来 说 ， 它 还 包括 动态 的 可 修改 性 ， 也 就 古 
部 畴 好 Web 服 务 右 后 可 以 在 不 集 止 、 不 重启 服务 的 前 提 下 ， 提 供给 


户 不 同 的 、 符 合 需求 的 功能 。 可 修改 性 可 以 进一步 分 解 为 可 进化 性 、 
可 扩展 性 、 可 定制 性 、 可 配置 性 和 可 重用 性 ， 下 面 简单 说 明 一 下 这 些 
概念 。 

(1) 可 进化 性 

可 进化 性 表示 我 们 在 修改 一 个 组 件 时 ， 对 其 他 组 件 产 生 人 负面 影响 
的 程度 。 当 然 ， 每 个 组 件 的 可 进化 性 都 是 不 同 的 ， 越 是 核心 的 组 件 其 


可 进化 性 可 能 会 越 低 ， 也 就 是 说 ， 对 这 个 组 件 的 功能 做 出 修改 时 可 能 
同时 必须 修改 其 他 大 量 的 相关 组 件 。 


对 于 Web 服 务 器 来 说 , “进化 "这 个 概念 按照 服务 是 否 在 运行 中 又 
可 以 分 为 静态 进化 和 动态 进化 。 优 秀 的 静态 进化 主要 依赖 于 架构 的 设 
计 是 否 足 够 抽象 ， 而 动态 进化 则 不 然 ， 它 与 整个 服务 的 设计 都 是 相关 
的 。 


(2) 可 扩展 性 


可 扩展 性 表示 将 一 个 新 的 功能 添加 到 系统 中 的 能 力 不 影响 其 他 
功能 ) 。 与 可 进化 性 一 样 ， 除 了 静态 可 扩展 性 外 ， 还 有 动态 可 扩展 性 
(如 有 果 已 经 部 署 的 服务 在 不 停止 、 不 重启 情况 下 添加 新 的 功能 ， 就 称 
为 动态 可 扩展 性 ) 。 


(3) 可 定制 性 


可 定制 性 是 指 可 以 临时 性 地 重新 规定 一 个 组 件 或 其 他 架构 元 素 的 
特性， 从 而 提供 一 种 非常 规 服 务 的 能 力 。 如 果 某 一 个 组 件 是 可 定制 
的 ， 那 么 是 指 用 户 能 够 扩展 该 组 件 的 服务 ， 而 不 会 对 其 他 客户 产生 影 
啊 。 文 持 可 定制 性 的 风格 一 般 会 提高 简单 性 和 可 扩展 性 ， 因 为 通 向 情 
况 下 只 会 实现 最 常用 的 功能 ， 不 太 和 章 用 的 功能 则 区 由 用 户 重 新 定制 使 
用 ， 这 样 组 件 的 复杂 性 融 降 低 了 ， 鳌 个 服务 也 会 更 容易 扩展 。 


(4) 可 配置 性 


可 配置 性 是 指 在 web 服务 部 车 后 ， 通 过 对 服务 提供 的 配置 文件 进 
行 修改 ， 来 提供 不 同 的 功能 。 它 与 可 扩展 性 、 可 重用 性 相关 。 


(5) 可 重用 性 


可 重用 性 指 的 是 一 个 应 用 中 的 功能 组 件 在 不 被 修改 的 情况 下 ， 可 
以 在 其 他 应 用 中 重用 的 程度 。 


5. 可 见 性 


在 Web 服 务 器 这 个 应 用 场景 中 ， 可 见 性 通常 是 指 一 些 天 键 组 件 的 
运行 情况 可 以 被 监控 的 程度 。 例 如 ， 服 务 中 正在 交互 的 网 络 连接 数 、 
缓存 的 使 用 情况 等 。 通 过 这 种 监控 ， 可 以 改善 服务 的 性 能 ， 尤 其 是 可 


四 信用 


6. 可 移植 性 


可 移植 性 是 指 服务 可 以 跨 平 台 运行 ， 这 也 是 当下 Nginx 被 大 规模 使 
用 的 必要 条 件 。 


7. 可 靠 性 


可 靠 性 可 以 看 做 是 在 服务 出 现 部 分 故障 时 ， 一 个 架构 容易 受到 系 
统 层面 故障 影响 的 程度 。 可 以 通过 以 下 方法 提高 可 靠 性 : 避免 单 点 故 
隐 、 增 加 元 余 、 人 允许 监视 ， 以 及 用 可 恢复 的 动作 来 缩小 故障 的 范围 。 


8.2 Nginx 的 架构 设计 


8.1 市 列 出 了 进行 Nginx 设 计时 需要 格外 重视 的 7 个 关键 点 ， 本 市 将 
介绍 Nginx 是 如 何在 这 7 个 关键 点 上 提升 Nginx 能 力 的 。 


8.2.1 ”优秀 的 模块 化 设计 


高 度 模块 化 的 设计 是 Nginx 的 架构 基础 。 在 Nginx 中 ， 除 了 少量 的 
核心 代码 ， 其 他 一 切 丝 为 模块 。 这 种 模块 化 设计 同时 具有 以 下 几 个 特 
感 : 


(1) 高 度 抽象 的 模块 接口 


所 有 的 模块 都 遵循 着 同样 的 ngx_module_t 接 口 设计 规范 ， 这 减少 了 
整个 系统 中 的 变数 ， 对 于 8.1 世 中 列 出 的 关键 关注 点 ， 这 种 方式 市 来 了 
民 好 的 和 商 单 性 、 静 仿 可 扩展 性 、 可 重用 性 。 


(2) 模块 接口 非常 简单 ， 具 有 很 高 的 灵活 性 


模块 的 基本 接口 ngx_module_t 足 够 人 简单， 只 涉及 模块 的 初始 化 、 退 
出 以 及 对 配置 项 的 处 理 ， 这 同时 也 市 来 了 足够 的 灵活 性 ， 使 得 Nginx 比 
较 简 单 地 实现 了 动态 可 修改 性 (参见 8.5 节 和 8.6 条 ， 可 知 如 何 通 过 HUP 


言 号 在 服务 正常 运行 时 使 新 的 配置 文件 生效 ， 以 及 通过 USR2 信 号 实现 
平滑 升级 ) ， 也 就 是 保持 服务 正常 运行 下 使 系统 功能 发 生 改 变 。 


如 图 8-1 所 示 ，ngx_module_t 结 构 体 作为 所 有 模块 的 通用 接口 ， 它 
只 定义 了 了 init_master 、init_module 、init_process 、init_thread 、 


exit_thread、exit_process、exit_master 这 7 个 回调 方法 (事实 上 ， 


init_master 、init_thread、exit_thread 这 3 个 方法 目前 都 没有 使 用 ) ， 它 们 
负责 模块 的 初始 化 和 退出 ， 同 时 它们 的 权限 也 非常 高 ， 可 以 处 理 系统 
的 核心 结构 体 ngx_cycle_t。 在 8.4T~8.6 季 中， 可 以 看 到 以 上 7 个 回调 方 
法 何 时 会 被 调用 。 而 ngx_command t 类 型 的 commands 数 组 则 指定 了 模 
块 处 理 配 置 项 的 方法 ( 详 见 第 4 章 ) 。 


除了 简单 、 基 础 的 接口 ，ngx_module t 中 的 ctx 成 员 还 是 一 个 void* 
指针 ， 它 可 以 指向 任何 数据 ， 这 给 模块 提供 了 很 大 的 灵活 性 ， 使 得 下 
面 将 要 介绍 的 多 层次 、 多 类 型 的 模块 设计 成 为 可 能 。ctx 成 员 一 般 用 于 
表示 在 不 同类 型 的 模块 中 一 种 类 型 模块 所 具备 的 通用 性 接口 。 


(3) 配置 模块 的 设计 


可 以 注意 到 ，ngx_module_t 接 口 有 一 个 type 成 员 ， 它 指明 了 Nginx 
允许 在 设计 模块 时 定义 模块 类 型 这 个 概念 ， 允 许 专注 于 不 同 领 域 的 模 
块 按照 类 型 来 区 别 。 而 配置 类 型 模块 是 唯一 一 种 只 有 1 个 模块 的 模块 类 
型 。 配 置 模块 的 类 型 叫做 NGX_CONF_MODULE， 它 仅 有 的 模块 叫做 


ngx_conf_module, 这 是 Nginx 最 瓜 层 的 模块 ， 它 指导 着 所 有 模块 以 配置 
项 为 核心 来 提供 功能 。 因 此 ， 它 是 其 他 所 有 模块 的 基础 。 配 置 模块 使 
Nginx 提 供 了 高 可 配置 性 、 高 可 扩展 性 、 高 可 定制 性 、 高 可 伸缩 性 。 


name 
-+create _ conf 
Hnit conf 


ngx http modulet 
+preconfiguration 
+postconfiguration 
+create Imain conf 
Hnit main conf 
+create _STV_conf 
+merge srv_conf 
+create loc conf 
+merge loc conf 


ngx event module t 


tprocess _changes 
+process events 
+init 


将 具体 化 
ctx 上 下 文 


+ctx_index 
+index 

+ spare 0-3 

+ Version 

+ ctx 
+commands:ngx command t 
+type 

+spare hook0-7 
+init _master 
+init module 
init _process 
+init _thread 
+exit thread 
+exit process 

+ exit _master 


图 8-1 ngx_module_t 接 口 及 其 对 核心 、 事件、HTTP、mail 等 4 类 模块 
ctx 上 下 文成 员 的 具体 化 


(4) 核心 模块 接口 的 简单 化 


Nginx 还 定义 了 一 种 基础 类 型 的 模块 : 核心 模块 ， 它 的 模块 类 型 叫 
做 NGX_CORE MODULE 。 目 前 官方 的 核心 类 型 模块 中 共有 6 个 具体 模 


块 ， 分 别 是 ngx_core_module 、ngx_errlog_module、 


ngx_events _ module 、 ngx_openssl module ~ ngx_http_module 、 


ngx_mail_module 模 块 。 为 什么 要 定义 核心 模块 呢 ? 因为 这 样 可 以 简化 


Nginx 的 设计 ， 


使 得 非 模 块 化 的 框架 代码 只 天 注 于 如 何 调 用 6 个 核心 模 


块 〈 大 部 分 Nginx 模 块 都 是 非 核心 模块 ) 。 


核心 模块 的 接口 非常 简单 ， 如 图 8-1 所 示 ， 它 将 ctx 上 下 文 进一步 实 
例 化 为 ngx_core_module t 结 构 体 ， 代 码 如 下 。 


typedef struct { 
// 核心 模块 名 称 


ngx_str_t name; 


// 解析 配 


Nginx 框 架 会 调用 


项 前 ， 


create_conf 方 法 


void *(*create conf)(ngx_cycle t *cycle) 


// 解析 配 


Nginx 框 架 会 调 


init_conf 方 法 


项 完成 后 ， 


char *(*init_ conf)(ngx_cycle t *cycle, void *conf); 
} ngx_core module_t; 


ngx_core_module_t 上 下 文 是 以 配置 项 的 解析 作为 基础 的 ， 它 提供 
了 create_conf 回 调 方法 来 创建 存储 配置 项 的 数据 结构 ， 在 读 取 
nginx.conf 配 置 文件 时 ， 会 根据 模块 中 的 ngx_command_t 把 解析 出 的 配 
置 项 存放 在 这 个 数据 结构 中 ， 它 还 提供 了 init_conf 回 调 方法 ， 用 于 在 解 
析 完 配置 文件 后 ， 使 用 解析 出 的 配置 项 初始 化 核心 模块 功能 。 除 此 以 
外 ，Nginx 框 以 不 会 约束 核心 模块 的 接口 、 功 能 ， 这 种 向 活 、 有 灵活 的 设 
计 为 Nginx 实 现 动态 可 配置 性 、 动 态 可 扩展 性 、 动 态 可 定制 性 市 来 了 极 
大 的 便利 ， 这 样 ， 在 每 个 模块 的 功能 实现 中 就 会 较 少 地 考虑 如 何不 停 
止 服 务 、 不 重启 服务 来 实现 以 上 功能 。 


这 种 设计 也 使 得 每 一 个 核心 模块 都 可 以 自由 地 定义 全 新 的 模块 类 
型 。 因 此 ， 作 为 核心 模块 ，ngx_events_module 定 义 了 
NGX_EVENT_MODULE 模 块 类 型 ， 所 有 事件 类 型 的 模块 都 由 
ngx_events_module 核 心 模块 管理 ，ngx_http_module 定 义 了 
NGX_HTTP_MODULE 模 块 类 型 ， 所 有 HTTP 类 型 的 模块 都 由 
ngx_http_module 核 心 模 块 管理 ， 而 ngx_mail_module 定 义 了 
NGX_MAIL_MODULE 模 块 类 型 ， 所 有 MAIL 类 型 的 模块 则 都 由 


ngx_mail _ module 核心 模块 管理 。 


(5) 多 层次 、 多 类 别 的 模块 设计 


所 有 的 模块 间 是 分 层次 、 分 类 别 的 ， 家 方 Nginx 共 有 五 大 类 型 的 模 
块 : 核心 模块 、 配 置 模块 、 事 件 模块 、HITP 模 块 、mail 模 块 。 虽 然 它 


们 都 具备 相同 的 ngx_module t 接 口 ， 但 在 请 求 处 理 流程 中 的 层次 并 不 相 
同 。 束 如 同上 面 介绍 过 的 核心 模块 一 样 ， 事 件 模块 、HTTP 模 块 、mail 
模块 都 会 再 次 具体 化 ngx_module_t 接 口 (由 于 配置 类 型 的 模块 只 拥有 1 
个 模块 ， 所 以 没有 具体 化 ctx 上 下 文成 员 ) ， 如 图 8-2 所 示 。 


图 8-2 展 示 了 Nginx 第 用 模块 间 的 关系 。 配 置 模 块 和 核心 模块 这 两 种 
模块 类 型 是 由 Nginx 的 框 染 代码 所 定义 的 ， 这 里 的 配置 模块 是 所 有 模块 
的 基础 ， 它 实现 了 最 基本 的 配置 项 解析 功能 (就 是 解析 nginx.conf 文 
件 ) 。Nginx 框 架 还 会 调用 核心 模块 ， 但 是 其 他 3 种 模块 都 不 会 与 框架 
广 生 直接 关系 。 事 件 模 块 、HTTP 模 块 、mail 模 块 这 3 种 模块 的 共性 是 : 
实际 上 它们 在 核心 模块 中 各 有 1 个 模块 作为 目 己 的 “代言 人 ”， 并 在 同类 
模块 中 有 1 个 作为 核心 业务 与 管理 功能 的 模块 。 例 如 ， 事 件 模块 是 由 它 
的 “代言 人 ”一 一 ngx_events_module 核 心 模 块 定义 ， 所 有 事件 模块 的 加 
载 控 作 不 是 由 Nginx 框 染 完 成 的 ， 而 是 由 ngx_event_core_module 模 块 负 
责 的 。 同 样 ，HTTP 模 块 是 由 它 的 “代言 人 >” 
块 定义 的 ， 与 事件 模块 不 同 的 是 ， 这 个 核心 模块 还 会 负 贡 加 载 所 有 的 
HTTP 模 块 ， 但 业务 的 核心 逻辑 以 及 对 于 有 具体 的 请 求 该 选用 哪 一 个 
HTTP 模 块 处 理 这 样 的 工作 ， 则 是 由 ngx_http_core_module 模 块 决定 的 。 
至 于 mail 模 块 ， 因 与 HTTP 模 块 基本 相似 ， 不 再 苯 述 。 


ngx_http_module 核 心 模 


mail 模块 


ngx_mail_core _module ngx_mail imap_ module 
核心 模块 
ngx_mail _proxy_module ngx_mail _pop3_module 


ngx_mail ssl] _module ngx_mail_smtp_module ngx_mail_module 


(定义 mail 模 块 ) 


HTTP 模 块 


ngx_http _core _module ngx_http _headers_filter _ module 


ngx_http _module 


( 定义 HTTP 模 块 ) 


ngx_http _log _module ngx_http _write _filter _module 


ngx_http _upstream_module ngx_http _rewrite _ module 
ngx_http _static _module ngx_http _proxy_module 


ngx_openssl _module 


ngx_events _module 
事件 模块 十 牛 


ne 
(定义 事件 模块 ) 
nex_epoll _module 
ngx_select _ module ngx_kqueue_module 
ngx_poll_ moduje [_ ngaio_module | 


ngx_core _module 


图 8-2 ”Nginx 常 用 模块 及 其 之 间 的 天 系 


在 这 5 种 模块 中 ， 配 置 模 块 与 核心 模块 都 是 与 Nginx 框 以 密切 相关 
的 ， 是 其 他 和 模块 的 基础 。 而 事件 模块 则 是 HTTP 模 块 和 mail 模 块 的 基 
础 ， 原 因 参 见 8.2.2 方 。HTTP 模 块 和 mail 模 块 的 “地 位 相似， 它们 都 更 
关注 于 应 用 层面 。 在 事件 模块 中 ，ngx_event_core_module 事 件 模 块 是 其 


他 所 有 事件 模块 的 基础 ， 在 HTTP 模 块 中 ，ngx_http_core_module 模 块 是 
其 他 所 有 HTTP 模 块 的 基础 ， 在 mail 模 块 中 ，ngx_mail_core_module 模 块 
是 其 他 所 有 mail 模 块 的 基础 。 


8.2.2 ”事件 驱动 架构 


所 谓 事件 驱动 忍 构 ， 人 简单 来 说 ， 束 是 由 一 些 事件 发 生源 来 产生 事 
件 ， 由 一 个 或 关 多 个 事件 收集 货 来 收集 、 分 发 事件 ， 然 后 许多 事件 处 
理 器 会 注册 自己 感 兴趣 的 事件 ， 同 时 会 “消费 ”这 些 事件 。 


对 于 Nginx 这 个 Web 服 务 器 而 言 ， 一 般 会 由 网 卡 、 磁 副 产 生 事件 ， 
而 8.2.1 方 中 提 到 的 事件 模块 将 负责 事件 的 收集 、 分 发 操作 ， 而 所 有 的 
模块 都 可 能 是 事件 消费 者 ， 它 们 首先 需要 疝 事件 模块 注册 感 兴 趣 的 事 
件 类 型 ， 这 样 ， 在 有 事件 产生 时 ， 事 件 模块 会 把 事件 分 发 到 相应 的 模 
块 十 壕 行 处 理 % 


Nginx 采 用 完全 的 事件 弛 动 架构 来 处 理 业 务 ， 这 与 传统 的 Web 服 务 
器 (如 Apache) 是 不 同 的 。 对 于 传统 Web 服 务 器 而 言 ， 采 用 的 所 谓 事件 
驱动 往往 局 限 在 TCP 连 接 建 立 、 关 闭 事 件 上 ， 一 个 连接 建立 以 后 ， 在 其 
关闭 之 前 的 所 有 操作 都 不 再 是 事件 驱动 ， 这 时 会 退化 成 按 序 执行 每 个 
操作 的 批 处 理 模 式 ， 这 样 每 个 请 求 在 连接 建立 后 都 将 始终 占用 着 系统 
质 源 ， 直 到 连接 关闭 才 会 释放 货源 。 要 知道 ， 这 段 时 间 可 能 会 非常 
长 ， 从 1 盈 秒 到 1 分 钟 都 有 可 能 ， 而 且 这 段 时 间 内 占用 看 内 存 、CPU 等 


资源 也 许 并 没有 意义 ， 整 个 事件 消费 进程 只 是 在 等 待 某 个 条 件 而 已 ， 
造成 了 服务 器 资源 的 极 大 浪费 ， 影 响 了 系统 可 以 处 理 的 并 发 连接 数 。 
如 图 8-3 所 示 ， 这 种 传统 Web 服 务 如 往 往 把 一 个 进程 或 线程 作为 事件 消 
费 者 ， 当 一 个 请 求 产生 的 事件 被 该 进程 处 理 时 ， 直 到 这 个 请 求 处 理 结 
束 时 进程 唤 源 都 将 被 这 一 个 请 求 所 占用 。 


图 8-3 ”传统 Web 服 务 絮 处理 事件 的 简单 模型 (椭圆 代表 数据 结构 ， 甜 
形 代表 进程 ) 


Nginx 则 不 然 ， 它 不 会 使 用 进程 或 线程 来 作为 事件 消费 者 ， 所 请 的 
事件 消费 者 只 能 是 某 个 模块 (在 这 里 没有 进程 的 概念 ) 。 只 有 事件 收 
集 、 分 发 右 才 有 资格 占用 进程 资源 ， 它 们 会 在 分 发 某 个 事件 时 调用 事 
件 消 费 模 块 使 用 当前 占用 的 进程 资源 ， 如 图 8-4 所 示 。 


图 8-4 中 列 出 了 5 个 不 同 的 事件 ， 在 事件 收集 、 分 发 者 进程 的 一 次 处 
理 过 程 中 ， 这 5 个 事件 按照 顺序 被 收集 后 ， 将 开始 使 用 当前 进程 分 发 事 
件 ， 从 而 调用 相应 的 事件 消费 着 模块 来 处 理事 件 。 当 然 ， 这 种 分 发 、 
调用 也 是 有 序 的 。 


从 上 面 的 内 容 可 以 看 出 传统 Web 服 务 右 与 Nginx 间 的 重要 差别 : 前 
古 每 个 事件 消费 着 独占 一 个 进程 资源 ， 后 考 的 事件 消费 着 只 古 被 事 
件 分 发 者 进程 短期 调用 而 已 。 这 种 设计 使 得 网 络 性 能 、 用 户 感知 的 请 
求 时 延 〈 延 时 性 ) 都 得 到 了 提升 ， 每 个 用 户 的 请 求 所 产生 的 事件 会 及 
时 啊 应 ， 整 个 服务 部 的 网 络 吞 吐 量 都 会 由 于 事件 的 及 时 啊 应 而 增 大 。 
但 这 也 会 市 来 一 个 重要 的 束 端 ， 即 每 个 事件 消费 者 都 不 能 有 阻塞 行 
为 ， 否 则 将 会 由 于 长 时 间 占 用 事件 分 发 考 进程 而 导致 其 他 事件 得 不 到 
及 时 啊 应 。 尤 其 是 每 个 事件 消费 者 不 可 以 让 进程 转变 为 休眠 状态 或 等 
答 状 态 ， 如 在 等 等 一 个 信号 量 条 件 的 满足 时 会 使 进程 进入 休眠 状态 。 
这 加 大 了 事件 消费 程序 的 开发 者 的 编程 难度 ， 因 此 ， 这 也 导致 了 Nginx 
的 模块 开发 相对 于 Apache 来 说 复杂 不 少 (上 文 已 经 提 到 过 ) 。 
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图 8-4 Nginx 处 理事 件 的 简单 模型 
8.2.3 ”请 求 的 多 阶段 异步 处 理 


这 里 所 讲 的 多 阶段 异步 处 理 请 求 与 事件 驱动 架构 是 密切 相关 的 ， 
换 句 话说 ， 请 求 的 多 阶段 异步 处 理 只 能 基于 事件 驱动 架构 实现 。 什 么 
意思 呢 ? 就 是 把 一 个 请 求 的 处 理 过 程 按照 事件 的 触发 方式 划分 为 多 个 
阶段 ， 每 个 阶段 都 可 以 由 事件 收集 、 分 发 如 来 触发 。 


例如 ， 处 理 一 个 获取 静态 文件 的 HTTP 请 求 可 以 分 为 以 下 几 个 阶段 
( 见 表 8-1) 。 


表 8-1 处 理 获取 静态 文件 的 HTTP 请 求 时 切 分 的 阶段 及 各 阶段 的 触发 事 
作 


阶段 意义 触发 事件 
建立 TCP 连接 接收 到 TCP 中 的 SYN 包 
开始 接收 用 户 请 求 接收 到 TCP 中 的 ACK 包 表 示 连 接 建 立成 功 
接收 到 用 户 请 求 并 分 析 已 接收 的 请 求 是 否 完 整 接收 到 用 户 的 数据 包 
接收 到 完整 的 用 户 请 求 后 开始 处 理 用 户 请 求 接收 到 用 户 的 数据 包 
申 目标 静态 文件 中 读 取 部 分 内 容 (避免 长 期 阻塞 事 | 接收 到 用 户 的 数据 包 ; 或 者 接收 到 TCP 中 的 ACK 包 表 示 
件 分 发 者 进程 ) 并 直接 发 送 给 用 户 用 户 已 接收 到 上 次 发 送 的 数据 包 ，TCP 滑动 窗口 向 前 滑动 


触发 事件 
接收 到 TCP 中 的 ACK 包 表 示 用 户 已 接收 到 之 前 发 送 的 所 
有 数据 包 
接收 到 TCP 中 的 FN 包 


阶段 意义 
对 于 非 keep-alive 请 求 ， 在 发 送 完 静态 文件 后 主动 
关闭 连接 
由 于 用 户 关 闭 连 接 而 结束 请 求 


这 个 例子 中 大 致 分 为 7 个 阶段 ， 这 些 阶段 是 可 以 重复 发 生 的 ， 因 
此 ， 一 个 下 载 静 仿 资源 请 求 可 能 会 由 于 请 求 数据 过 大 、 网 速 不 稳定 等 
因素 而 被 分 解 为 成 日 上 千 个 表 8-1 中 所 列 出 的 阶段 。 


异步 处 理 和 多 阶段 是 相辅相成 的 ， 只 有 把 请 求 分 为 多 个 阶段 ， 才 
有 所 谓 的 异步 处 理 。 也 吏 是 说 ， 当 一 个 事件 被 分 发 到 事件 消费 者 中 进 
行 处 理 时 ， 事 件 消费 者 处 理 完 这 个 事件 只 相当 于 处 理 完 1 个 请 求 的 某 个 
阶段 。 什 么 时 候 可 以 处 理 下 一 个 阶段 呢 ? 这 只 能 等 竺 内 核 的 通知 ， 即 
当下 一 次 事件 出 现时 ，epoll 等 事件 分 发 右 将 会 获取 到 通知 ， 青 继续 调 
用 事件 消费 者 处 理 请 求 。 这 样 ， 每 个 阶段 中 的 事件 消费 者 部 不 清 苞 
次 完整 的 操作 冤 竟 什么 时 候 会 完成 ， 只 能 异步 被 动 地 等 竺 下 一 次 事件 
的 通知 。 


请 求 的 多 阶段 异步 处 理 优势 在 哪里 ? 这 种 设计 配合 事件 驱动 染 
构 ， 将 会 极 大 地 提高 网 络 性 能 ， 同 时 使 得 每 个 进程 都 能 全 力 运转 ， 不 
会 或 者 尽量 少 地 出 现 进程 休眠 状况 。 因 为 一 旦 出 现 进程 休眠 ， 必 人 然 减 
少 并 发 处 理事 件 的 数目 ， 一 定 会 降低 网 络 性 能 ， 同 时 会 增加 请 求 处 理 
时 间 的 平均 时 延 ! 这 时 ， 如 有 果 网 络 性 能 无 法 满足 业务 需求 将 只 能 增加 
进程 数目 ， 进 程 数 目 过 多 束 会 增加 操作 系统 内 核 的 额外 操作 ， 进 程 间 
切换 ， 可 是 频 粽 地 进行 进程 间 切 换 仍 会 消耗 CPU 等 贷 源 ， 从 而 降低 网 
络 性 能 。 同 时 ， 休 了 眠 的 进程 会 使 进程 占用 的 内 存 得 不 到 有 效 释 放 ， 这 
最 终 必然 导致 系统 可 用 内 存 的 下 降 ， 从 而 影响 系统 能 够 处 理 的 最 大 并 
发 连接 效 。 


根据 什么 原则 来 划分 请 求 的 阶段 呢 ? 一 般 是 找到 请 求 处 理 流 程 中 
的 阻塞 方法 (或 者 造成 阻塞 的 代码 段 ，， 在 阻塞 代码 段 上 按照 下 面 4 种 
方式 来 划分 阶段 : 


(1) 将 阻塞 进程 的 方法 按照 相关 的 触发 事件 分 解 为 两 个 阶段 


一 个 本 身 可 能 导致 进程 休 眼 的 方法 或 系统 调用 ， 一 般 都 能 够 分 解 
为 多 个 更 小 的 方法 或 者 系统 调用 ， 这 些 调用 间 可 以 通过 事件 触发 关联 
起 来 。 大 部 分 情况 下 ， 一 个 阻塞 进程 的 方法 调用 时 可 以 划分 为 两 个 阶 
段 : 阻塞 方法 改 为 非 阻塞 方法 调用 ， 这 个 调用 非 阻 塞 方法 并 将 进程 归 
还 给 事件 分 发 器 的 阶段 束 吓 第 一 阶段 ， 增 加 新 的 处 理 阶 段 (第 二 阶 


段 ) 用 于 处 理 非 阻塞 方法 最 终 返 回 的 结果 ， 这 里 的 结果 返回 事件 就 是 
第 二 阶段 的 触发 事件 。 


例如 ， 在 使 用 send 调 用 发 送 数据 给 用 户 时 ， 如 果 使 用 阻塞 socket 句 
柄 ， 那 么 send 调 用 在 回 操 作 系统 内 核发 出 数据 包 后 束 必 须 把 当前 进程 休 
有 眠 ， 直 到 成 功 发 出 数据 才能 “ 醒 来 *。 这 时 的 send 调 用 发 送 数 据 并 等 待 结 
果 。 我 们 需要 把 send 调 用 分 解 为 两 个 阶段 : 发 送 且 不 等 待 结 有 果 阶 段 、 
send 结 采 返 回 阶段 。 因 此 ， 可 以 使 用 非 阻塞 socket 句 柄 ， 这 样 调用 send 
发 送 数据 后 ， 进 程 写 不 会 进入 休眠 的 ， 这 了 束 是 发 送 且 不 等 生 结 末 阶 
段 ， 再 把 socket 人 句柄 加 入 到 事件 收集 各 中 束 可 以 等 竺 相应 的 事件 触发 下 
一 个 阶段 ，send 发 送 的 数据 被 对 方 收 到 后 这 个 事件 束 会 触发 send 结 末 返 


回 阶段 。 这 个 send 调 用 束 是 请 求 的 划分 阶段 点 。 


(2) 将 阻塞 方法 调用 按照 时 间 分 解 为 多 个 阶段 的 方法 调用 


注意 ， 系 统 中 的 事件 收集 、 分 发 者 并 非 可 以 处 理 任何 事件 。 如 果 
按照 前 一 种 方式 试图 划分 某 个 方法 时 ， 那 么 可 能 会 发 现 找 出 的 触发 事 
件 不 能 够 被 事件 收集 、 分 发 器 所 处 理 ， 这 时 只 能 按照 执行 时 间 来 拆 分 


这 个 方法 了 。 


例如 读 取 文件 的 调用 ( 非 异步 WO) ， 如 果 我 们 读 取 10MB 的 文 
件 ， 这 些 文件 在 磁盘 中 的 块 未 必 是 连续 的 ， 这 意味 着 当 这 10MB 文 件 内 
容 不 在 操作 系统 的 缓存 中 时 ， 可 能 需要 多 次 驱动 硬盘 寻 址 。 在 寻 址 过 


程 中 ， 进 程 多 半 会 休眠 或 者 等 待 。 我 们 可 能 会 希望 像 上 文 所 说 的 那样 
把 读 取 文 件 调用 分 解 成 两 个 阶段 : 发 送 读 取 命 令 且 不 等 竺 结果 阶段 、 
读 取 结 果 返 回 阶段 。 这 样 当 然 很 好 ， 可 惜 的 是 ， 如 果 我 们 的 事件 收 
集 、 分 发 者 不 支持 这 么 做 ， 该 怎么 办 ? 例如 ， 在 Linux 上 Nginx 的 事件 
模块 在 没 打开 异步 JO 时 就 不 文 持 这 种 方法 ， 像 ngx_epoll_ module 模 块 主 
要 是 针对 网 络 事件 的 ， 而 主机 的 磁盘 事件 目前 还 不 支持 (必须 通过 内 
核 异步 WO) 。 这 时 ， 我 们 可 以 这 样 来 分 解读 取 文 件 调用 : 把 10MB 均 
分 成 1000 份 ， 每 次 只 读 取 10KB。 这 样 ， 读 取 10KB 的 时 间 就 是 可 控 的 ， 
意味 着 这 个 事件 接收 器 占用 进程 的 时 间 不 会 太 久 ， 整 个 系统 可 以 及 时 
地 处 理 其 他 请 求 。 


那么 ， 在 读 取 0OKB~10KB 的 阶段 完成 后 ， 怎 样 进入 10KB~20KB 阶 
段 呢 ? 这 有 很 多 种 方式 ， 如 读 取 完 10KB 文 件 后 ， 可 能 需要 使 用 网 络 来 
发 送 它们 ， 这 时 可 以 由 网 络 事件 来 触发 。 或 者 ， 如 果 没 有 网 络 事件 ， 
也 可 以 设置 一 个 简单 的 定时 器 ， 在 某 个 时 间 点 后 再 次 调用 下 一 个 阶 
段 o 


(3) 在 “无 所 事 事 ” 且 必须 等 待 系统 的 响应 ， 从 而 导致 进程 空转 
时 ， 使 用 定时 器 划分 阶段 


有 时 阻塞 的 代码 段 可 能 是 这 样 的 : 进行 采 个 无 阻塞 的 系统 调用 
后 ， 必 须 通过 持续 的 检查 标志 位 来 确定 是 否 继续 向 下 执行 ， 当 标志 位 
没有 获得 满足 时 殉 循 环 地 检查 下 去 。 这 样 的 代码 段 本 号 没 有 阻塞 方法 


调用 ， 可 实际 上 是 阻塞 进程 的 。 这 时 ， 应 该 使 用 定时 器 来 代替 循环 检 
查 标 志 ， 这 样 定 时 器 事件 发 生 时 束 会 先 检 查 标志 ， 如 果 标 志 位 不 满 
足 ， 就 立刻 归还 进程 控制 权 ， 同 时 继续 加 入 期 望 的 下 一 个 定时 器 事 
人 


(4) 如 果 阻 塞 方法 完全 无 法 继续 划分 ， 则 必须 使 用 独立 的 进程 执 
行 这 个 阻塞 方法 


如 采 肝 个 方法 调用 时 可 能 导致 进程 休眠 ， 或 者 占用 进程 时 间 过 
长 ， 可 是 又 无 法 将 该 方法 分 解 为 不 阻塞 的 方法 ， 那 么 这 种 情况 旦 与 事 
件 红 动 架构 相 违 育 的 。 通 音 生 由 于 这 个 方法 的 实现 着 没有 开放 非 阻 塞 
接口 所 导致 ， 这 时 必须 通过 产生 新 的 进程 或 者 指定 茶 个 非 事件 分 发 者 
进程 来 执行 阻塞 方法 ， 并 在 阻塞 方法 执行 完毕 时 向 事件 收集 、 分 发 者 
进程 发 送 事件 通知 继续 执行 。 因 此 ， 至 少 要 拆 分 为 两 个 阶段 : 阻塞 方 
法 执行 前 阶段 、 阻 塞 方法 执行 后 阶段 ， 而 阻塞 方法 的 执行 要 使 用 单独 
的 进程 去 调度 ， 并 在 方法 返回 后 发 送 事件 通知 。 一 旦 出 现 上 面 这 种 设 
计 ， 我 们 必须 审视 这 样 的 事件 消费 者 是 否 足 够 合理 ， 有 没有 必要 用 这 
种 违反 事件 驱动 淋 构 的 方式 来 解决 阻 窄 问 题 。 


请 求 的 多 阶段 异步 处 理 将 会 提高 网 络 性 能 、 降 低 请 求 的 时 延 ， 在 
与 事件 续 动 架构 配合 工作 后 ， 可 以 使 得 Web 服 务 右 同时 处 理 十 万 甚至 百 
万 级 别 的 并 发 连接 ， 我 们 在 开发 Nginx 模 块 时 必须 遵循 这 一 原则 。 


8.2.4 ”管理 进程 、 多 工作 进程 设计 


Nginx 采 用 一 个 master 管 理 进 程 、 多 个 worker 工 作 进 程 的 设计 方 
式 ， 如 图 8-5 所 示 。 


cache 


manager 


进程 


图 8-5 Nginx 采 用 的 一 个 master 管 理 进程 、 多 个 工作 进程 的 设计 方式 


在 图 8-5 中 ， 包 括 完全 相同 的 worker 进 程 、1 个 可 选 的 cache manager 
进程 以 及 1 个 可 选 的 cache loader 进 程 。 


这 种 设计 市 来 以 下 优点 : 
(1) 利用 多 核 系 统 的 并 发 处 理 能 
现代 操作 系统 已 经 文 持 多 核 CPU 架 构 ， 这 使 得 多 个 进程 可 以 占用 
不 同 的 CPU 核 心 来 工作 。 如 末 只 有 一 个 进程 在 处 理 请 求 ， 则 必然 会 造 
成 CPU 资 源 的 浪费 ! 如 果 多 个 进程 间 的 地 位 不 平等 ， 则 必然 会 有 某 一 


级 同一 地 位 的 进程 成 为 瓶颈 ， 因 此 ，Nginx 中 所 有 的 worker 工 作 进 程 都 
是 完全 平等 的 。 这 提高 了 网 络 性 能 、 降 低 了 请 求 的 时 延 。 


(2) 负载 均衡 


多 个 worker 工 作 进 程 问 通过 进程 间 通 信 来 实现 负载 均衡 ， 也 融 是 
说 ， 一 个 请 求 到 来 时 更 容易 被 分 配 到 负载 较 轻 的 worker 工 作 进程 中 处 
理 。 这 将 降低 请 求 的 时 延 ， 并 在 一 定 程度 上 提高 网 络 性 能 。 


(3) 管理 进程 会 负责 监控 工作 进程 的 状态 ， 并 负责 管理 其 行为 


管理 进程 不 会 占用 多 少 系统 资源 ， 它 只 是 用 来 启动 、 停 止 、 监 控 
或 使 用 其 他 行为 来 控制 工作 进程 。 首 先 ， 这 提高 了 系统 的 可 靠 性 ， 当 
工作 进程 出 现 问题 时 ， 管 理 进程 可 以 局 动 新 的 工作 进程 来 避免 系统 性 
能 的 下 降 。 其 次 ， 管 理 进程 支持 Nginx 服 务 运行 中 的 程序 升级 、 配 置 项 


的 修改 等 操作 ， 这 种 设计 使 得 动态 可 扩展 性 、 动 态 定制 性 、 动 态 可 进 
化 性 较 容易 实现 。 


8.2.5 平台 无 关 的 代码 实现 


在 使 用 C 语 言 实现 Nginx 时 ， 尽 量 减 少 使 用 与 操作 系统 平台 相关 的 
代码 ， 如 某 个 操作 系统 上 的 第 三 方 库 。Nginx 重 新 封装 了 日 志 、 各 种 基 
本 数据 结构 《如 第 7 章 中 介绍 的 容器 ) 、 第 用 算法 等 工具 软件 ， 在 核心 
代码 都 使 用 了 与 操作 系统 无 关 的 代码 实现 ， 在 与 操作 系统 相关 的 系统 
调用 上 则 分 别针 对 各 个 操作 系统 都 有 独立 的 实现 ， 这 最 终 造 就 了 Nginx 
的 可 移植 性 ， 实 现 了 对 主流 操作 系统 的 文 持 。 


8.2.6 ”内 存 池 的 设计 


为 了 避免 出 现 内 存 碎片 、 减 少 同 操 作 系统 申请 内 存 的 次 数 、 降 低 
各 个 模块 的 开发 复杂 度 ，Nginx 设 计 了 简单 的 内 存 池 。 这 个 内 存 池 没 有 
很 复 洒 的 功能 ， 通 向 它 不 负责 回收 内 存 池 中 已 经 分 配 出 的 内 存 。 这 种 
内 存 池 最 大 的 优 挟 在 于 : 把 多 次 同系 统 申请 内 存 的 操作 整合 成 一 次 ， 
这 大 大 减少 了 CPU 资源 的 消耗 ， 同 时 减少 了 内 存 雁 片 。 


因此 ， 通 常 每 一 个 请 求 都 有 一 个 这 种 简易 的 独立 内 存 池 (在 第 9 章 
中 会 看 到 ，Nginx 为 每 一 个 TCP 连 接 都 分 配 了 1 个 内 存 池 ， 而 在 第 10 章 和 
第 11 章 ，HTTP 框 架 为 每 一 个 HTTP 请 求 又 分 配 了 1 个 内 存 池 ) ， 而 在 请 


求 结束 时 则 会 销毁 整个 内 存 池 ， 把 曾经 分 配 的 内 存 一 次 性 归还 给 操作 
系统 。 这 种 设计 大 大 提高 了 模块 开发 的 简单 性 (如 在 前 几 间 中 开发 
HTTP 模 块 时 ， 申 请 内 存 后 都 不 用 关心 它 释放 的 问题 ， 而 且 因 为 分 配 
内 存 次 数 的 减少 使 得 请 求 执 行 的 时 延 得 到 了 降低 ， 同 时 ， 通 过 减少 内 
存 人 碎片 ， 提 高 了 内 存 的 有 效 利用 率 和 系统 可 处 理 的 并 发 连接 数 ， 从 而 
增强 了 网 络 性 能 。 


8.2.7 ”使 用 统一 管道 过 滤 右 模式 的 HTTP 过 滤 模 块 


有 一 类 HTTP 模 块 被 命名 为 HTTP 过 滤 模 块 ， 其 中 每 一 个 过 滤 模 块 
都 有 输入 痕 和 和 葵 出 端 ， 这 些 输入 端 和 输出 站 都 具有 统一 的 接口 。 这 些 
过 滤 模 块 将 按照 configure 执 行 时 决定 的 顺序 组 成 一 个 流水 线 式 的 加 工 
HTTP 啊 应 的 中 心 ， 每 一 个 过 滤 模 块 都 是 完全 独立 的 ， 它 处 理 着 输入 端 
接收 到 的 数据 ， 并 由 输出 端 传递 给 下 一 个 过 滤 模 块 。 每 一 个 过 滤 模 块 
都 必须 可 以 增 量 地 处 理 数据 ， 也 束 是 说 能 够 正确 处 理 完整 数据 访 的 一 


hs 


了 时 


这 种 统一 管理 过 滤 融 的 设计 方式 的 好 处 非常 明显 : 首先 它 允 许 把 
整个 HTTP 过 滤 系 统 的 输入 /和 输出 催化 为 一 个 个 过 滤 模 块 的 稍 单 组 合 ， 这 
大 大 提高 了 简单 性 ， 其 次 ， 它 提供 了 很 好 的 可 重用 性 ， 任 意 两 个 HTTP 
过 滤 模 块 都 可 以 连接 在 一 起 〈 在 可 允许 的 范围 内 ) ; 再 次 ， 整 个 过 滤 
系统 非常 容易 维护 、 增 强 。 例 如 ， 开 发 了 一 个 新 的 过 滤 模 块 后 ， 可 以 


非常 方便 地 添加 到 过 滤 系 统 中 ， 这 是 一 种 高 可 扩展 性 。 又 如 ， 昌 的 过 
滤 模 块 可 以 很 容易 地 被 升级 版 的 过 滤 模 块 所 替代 ， 这 是 一 种 高 可 进化 
性 ; 接着 ， 它 在 可 验证 性 和 可 测试 性 上 非常 友好 ， 我 们 可 以 灵活 地 杰 
动 这 个 过 滤 模 块 流水 线 来 验证 功能 ， 最 后 ， 这 样 的 系统 完全 文 持 并 发 
执行 。 


8.2.8 ”其 他 一 些 用 户 模 块 


Nginx 还 有 许多 特定 的 用 户 模 块 都 会 改进 8.1 市 中 提 到 的 约束 属性 。 
例如 ，ngx_http_stub_status_module 模 块 提 供 对 所 有 HTTP 连 接 状 态 的 监 
探 ， 这 就 提高 了 系统 可 见 性 。 而 ngx_http_gzip_filter_ module 过 滤 模 块 和 
ngx_http_gzip_static_module 模 块 使 得 相同 的 吞 叶 量 传送 了 更 多 的 信 
轧 ， 自 然 也 就 提高 了 网 络 效率 。 我 们 也 可 以 开发 这 样 的 模块 ， 让 Nginx 
变 得 更 好 。 


8.3 ”Nginx 杠 架 中 的 核心 结构 体 ngx_cydle_t 


Nginx 核 心 的 框架 代码 一 直 在 围绕 着 一 个 结构 体 展 开 ， 它 就 是 
ngx_cycle _t。 无 论 是 master 管 理 进 程 、worker 工 作 进 程 还 是 cache 
manager (loader) 进程 ， 每 一 个 进程 都 毫 无 例外 地 拥有 唯一 一 个 
ngx_cycle_t 结 构 体 。 服 务 在 初始 化 时 就 以 ngx_cycle_t 对 象 为 中 心 来 提供 
服务 ， 在 正常 运行 时 仍然 会 以 ngx_cycle_t 对 象 为 中 心 。 本 节 将 围绕 着 
ngx_cycle_t 结 构 体 的 定义 、ngx_cycle_t 结 构 体 所 支持 的 方法 来 介绍 
Nginx 框 架 代码 ， 其 中 8.4 节 中 的 Nginx 的 启动 流程 、8.5 节 和 8.6 节 中 
Nginx 各 进程 的 主要 工作 流程 都 是 以 ngx_cycle_t 结 构 体 作为 基础 的 。 下 
面 我 们 来 看 一 下 ngx_cycle_t 完 竟 有 哪些 成 员 维持 了 Nginx 的 基本 框架 。 


8.3.1 ngx_jlistening_t 结 构 体 


作为 一 个 Web 服务器 ，Nginx 首 移 需 要 监听 端口 并 处 理 其 中 的 网 络 
事件 。 这 本 来 应 该 属于 第 9 章 所 介绍 的 事件 模块 要 处 理 的 内 容 ， 但 由 于 
监听 端口 这 项 工作 是 在 Nginx 的 局 动 框架 代码 中 完成 的 ， 所 以 暂时 把 它 
放 到 本 章 中 介绍 。ngx_cycle_t 对 象 中 有 一 个 动态 数组 成 员 叫 做 
listening， 它 的 每 个 数组 元 素 都 是 ngx_listening_t 结 构 体 ， 而 每 个 
ngx_listening_t 结 构 体 又 代表 着 Nginx 服 务 器 监听 的 一 个 端口 。 在 8.3.2 市 
中 的 一 些 方法 会 使 用 ngx_listening_t 结 构 体 来 处 理 要 监听 的 端口 ， 在 8.4 


忆 中 我 们 也 会 看 到 master 进 程 、worker 进 程 等 许多 进程 如 何 监听 同一 个 
TCP 疹 口 〈fork 出 的 子 进程 自然 共享 打开 的 端口 ) 。 更 多 关于 
ngx_listening_t 的 介绍 将 在 第 9 章 中 介绍 。 丁 我 们 仅仅 介绍 
ngx_listening_t 的 成 员 ， 对 于 它 会 引用 到 的 其 他 对 象 ， 如 
ngx_connection_t 等 ， 将 在 第 9 章 中 介绍 。 下 面 来 看 一 下 ngx_listening_t 
的 成 员 ， 代 码 如 下 所 示 。 


typedef struct ngx_listening_s ngx_listening_t; 
struct ngx_listening _s { 
// socket 套 接 字 句柄 


ngx_socket_t fd; 
// 监听 


sockaddr 地 址 


Struct sockaddr *Ssockaddr 
// sockaddr 地 址 长 度 


Socklen t socklen; 


/* 存 储 


IP 地 址 的 字符 串 


addr_text 最 大 长 度 ， 即 它 指 定 


| 


addr_text 所 分 配 的 内 存 大 小 


*/ 
size_t addr_text_max_len,; 
// 以 字符 串 形 式 存 储 


IP 地 址 


ngx_str_t addr_text 
// 套 接 字 类 型 。 例 如 ， 当 


type 是 


SOCK_STREAM 时 ， 表 示 


TCP 
int type; 
/*TcP 变 现 监听 时 的 


back1og 队 列 ， 它 表示 允许 正在 通过 三 次 握手 建立 


TCP 连 接 但 还 没有 任何 进程 开始 处 理 的 连接 最 大 个 数 


Wy 
int backlog; 
// 内 核 中 对 于 这 个 套 接 字 的 接收 缓冲 区 大 小 


int rcvbuf; 


// 内 核 中 对 于 这 个 套 接 字 的 发 送 缓 促 区 大 小 


int sndbuf; 
// 当 新 的 


TCP 连 接 成 功 建立 后 的 处 理 方法 


ngx_connection handler_pt handler,; 
/* 实 际 上 框架 并 不 使 用 


servers 指 针 ， 它 更 多 是 作为 一 个 保留 指针 ， 目 前 主要 用 于 
HTTP 或 者 
mail 等 模块 ， 用 于 保存 当前 监听 端口 对 应 着 的 所 有 主机 名 


WA 
Vold *servers; 
// log 和 


logp 都 是 可 用 的 日 志 对 象 的 指针 


ngx_log_t log; 
ngx_log_t *logp; 
// 如 果 为 新 的 


TCP 和 连接 创建 内 存 池 ， 则 内 存 池 的 初始 大 小 应 该 是 


pool_size 
size_t pool size,; 
/*TCP_DEFER_ACCEPT 选 项 将 在 建立 


TCP 连 接 成 功 且 接 收 到 用 户 的 请 求 数据 后 ， 才 向 对 监听 套 接 字 感 > 
如 果 


post_accept_timeout 秒 后 仍然 没有 收 到 的 用 户 数据 ， 则 内 核 直接 丢弃 连接 


长 


趣 的 进程 发 送 事件 通知 ， 而 连接 建立 成 功 后 ， 


*/ 


ngx_msec_t post_accept_timeout; 
前 二 个 


ngx_listening_t 结 构 ， 多 个 


ngx_listening_t 结 构 体 之 间 


previous 指 针 组 成 单 链 表 


74 
ngx_listening t *previous; 


// 当前 监听 句柄 对 应 着 的 


ngx_connection_t 结 构 体 


ngx_connection t *connection; 
/* 标 志 位 ， 为 


入 | 


1 则 表示 在 当前 监听 句柄 有 效 ， 且 执行 


ngx_init_cycle 时 不 关闭 监听 端 


9 时 则 正常 关闭 。 该 标志 位 框架 代码 会 


*/ 


unsigned open:1; 
/* 标 志 位 ， 为 


1 表示 使 用 已 有 的 


ngx_cycle_t 来 初始 化 新 的 


动 设置 


ngx_cycle_t 结 构 体 时 ， 不 关闭 原先 打开 的 监听 端口 ， 这 对 运行 


remain 为 


09 时， 表示 了 


ngx_init_cycle 方 法 


*/ 


FE 常 关闭 曾经 


打 


的 监听 端口 。 该 标志 位 框架 代码 会 自 


unsigned remain:1,; 
/* 标 志 位 ， 为 


1 时 表示 跳 过 设置 当前 


ngx_listening_t 结 构 体 9 


0 时 正常 初始 化 套 接 字 。 该 标志 位 


*/ 


的 套 接 字 ， 为 


unsigned ignore:1,; 


// 


E 架 代码 会 自动 设置 


表示 是 否 已 经 绑 定 。 实 际 上 


目前 该 标志 位 没有 使 用 


unsigned bound:1; /* 已 经 绑 定 
*/ 
/* 表 示 当 前 监听 句柄 是 否 来 自前 一 个 进程 (如 升级 
Nginx 程 序 ) ， 如 果 为 
1， 则 表示 来 自前 一 个 进程 。 一 般 会 保留 之 前 已 经 设置 好 的 套 接 字 ， 不 做 改变 
二 / 
unsigned inherited:1;  /* 来 自前 一 个 进程 
*/ 
// 目前 未 使 用 


unsigned nonblocking_accept:1; 


中 升级 程序 很 有 用 ， 


// 标志 位 ,为 
1 时 表示 当前 结构 体 对 应 的 套 接 字 已 经 监听 


几 


unsigned listen:1; 
// 表示 套 接 字 是 否 阻塞 ， 目 前 该 标志 位 没有 意义 


unsigned nonblocking: 1; 
// 目前 该 标志 位 没有 意义 


unsigned shared:1; 


// 标志 位 ， 为 


1 时 表示 


Ngjinx 会 将 网 络 地 址 转变 为 字符 串 形 式 的 地 址 


unsigned addr_ntop:1; 


}; 


ngX_connection_handler_pt 类 型 的 handler 成 员 表 示 在 这 个 监听 端口 
上 成 功 建立 新 的 TCP 连 接 后 ， 束 会 回调 handler 方 法 ， 它 的 定义 很 简单 ， 
如 下 所 示 。 


typedef void (*ngx_connection_handler_pt)(ngx_connection t *c); 


它 接 收 一 个 ngx_connection_t 连 接 参 数 。 许 多 事件 消费 模块 (如 
HTTP 框 染 、mail 框 架 ) 都 会 目 定 义 上 面 的 handler 方 法 。 


8.3.2 ngx_cycle_t 结 构 体 


Nginx 框 架 是 围绕 着 ngx_cydle_t 结 构 体 来 控制 进程 运行 的 。 
ngx_cycle_t 结 构 体 的 prefix、conf_prefix、conf_file 等 字符 串 类 型 成 员 保 
存 着 Nginx 配 置 文件 的 路 径 ， 从 8.2 广 已 经 知道 ，Nginx 的 可 配置 性 完全 


依赖 于 nginx.conf 配 置 文件 ，Nginx 所 有 模块 的 可 定制 性 、 可 伸缩 性 等 诸 
多 特性 也 是 依赖 于 nginx.conf 配 置 文件 的 ， 可 以 想见 ， 这 个 配置 文件 路 
径 必 然 是 保存 在 ngx_cycle_t 结 构 体 中 的 。 


有 了 配置 文件 后 ， | 有 的 模块 
了 ， 这 一 步 又 会 在 ngx_init_cycle 方 法 中 进行 ( 见 8.3.3 节 ) 。 
ee 顾名思义 ， 就 是 用 来 构造 ngx_cycle_t 结 构 体 中 成 员 
的 ， 首 先 来 介绍 一 下 ngx_cycle_t 中 的 成 员 (对 于 下 面 提 到 的 
connections 、 read_events、write_events、files、free_connections 等 成 
们 是 与 事件 模块 强 相关 的 ， 本 章 将 不 做 详细 介绍 ， 在 第 9 章 中 会 


je 
详 述 这 些 成 员 的 意义 ) 


加 
Dal 


typedef struct ngx_cycle s ngx_cycle t; 
J ngx_cycle _s { 

/* 保 存 着 所 有 模块 存储 配置 项 的 结构 体 的 指针 ， 它 首先 是 一 个 数组 ， 每 个 数组 成 员 又 是 一 个 指针 ， 这 个 指 
针 指向 另 一 个 存储 着 指针 的 数组 ， 因 此 会 看 到 


VOid**** */ 
void ****conf_ctx; 


// 内 存 池 


由 poo]l_t *pool; 
志 模 块 中 提供 了 生成 基本 


ngx_1og_t 日 志 对 象 的 功能 ， 这 里 的 


10g 实 际 上 是 在 还 没有 执行 


ngx_init_cycle 方 法 前 ， 也 就 是 还 没有 解析 配置 前 ， 如 果 有 信息 需要 输出 到 日 志 ， 就 会 暂时 使 
10g 对 象 ， 它 会 输出 到 屏幕 。 在 


ngx_init_cycle 方 法 执行 后 ， 将 会 根据 


E 确 的 日 志文 件 ， 此 时 会 对 


nginx,conf 配 置 文件 中 的 配置 项 ， 构 造 出 


10g 重 新 赋值 


WA 
ngx_log_t *1log; 


/* 由 


nginx.conf 配 置 文件 读 取 到 日 志文 件 路 径 后 ， 将 开始 初始 化 


error_1og 日 志文 件 ， 由 于 


10g 对 象 还 在 用 于 输出 日 志 到 屏幕 ， 这 时 会 用 


new_10g 对 象 暂 时 性 地 替代 


10g 日 志 ， 待 初始 化 成 功 后 ， 会 


new_1og 的 地 址 覆盖 上 面 的 
1og 指 针 
6 


// 与 下 面 的 


ngx_log_t new_ log; 


files 成 员 配 合 使 用 ， 指 出 


files 数 组 里 元 素 的 总 数 


ngx_uint_t files_n; 
A 


poll、 


rtsig 这 样 的 事件 模块 ， 会 以 有 效 文件 句柄 数 来 预先 建立 这 些 


ngx_connection_t 结 构 体 ， 以 加 速 事件 的 收集 、 分 发 。 这 时 
files 就 会 保存 所 有 


ngx_connection_t 的 指针 组 成 的 数组 ， 


files_n 就 是 指针 的 总 数 ， 而 文件 句柄 的 值 用 来 访问 
files 数 组 成 员 
*/ 


ngx_connection_t **files,; 
// 可 用 连接 池 ， 与 


free_connection_n 配 合 使 


ngx_connection t *free_connections ; 
// 可 用 连接 池 中 连接 的 总 数 


ngx_uint_t free connection_n; 
/* 双 向 链表 容器 ， 元 素 类 型 是 


ngx_connection_t 结 构 体 ， 表 示 可 重复 使 用 连接 队列 


*/ 
ngx_queue_t reusable connections_ queue; 
/* 动 态 数 组 ， 每 个 数组 元 素 存 储 着 


ngx_listening_t 成 员 ， 表 示 监 听 端 口 及 相关 的 参数 


4 
ngx_array_t listening,; 
/* 动 态 数组 容器 ， 它 保存 着 


Nginx 所 有 要 操作 的 目录 。 如 果 有 目录 不 存在 ， 则 会 


Nginx 启 动 失败 。 例 如 ， 上 传 文件 的 临时 目录 也 在 


pathes 中 ， 如 果 没 有 权限 创建 ， 则 会 导致 


Nginx 无 法 启动 
*/ 


ngx_array_t pathes; 
/* 单 链表 容器 ， 元 素 类 型 是 


ngx_open_file_t 结 构 体 ， 它 表 亡 


pa 


[TT 


Nginx 已 经 打开 的 所 有 文件 。 事 实 j 


Nginx 框 架 不 会 向 


open_files 链 表 中 添加 文件 ， 而 是 
Nginx 框 架 会 在 


ngx_init_cycle 方 法 中 打开 这 些 文件 


%/ 
ngx_list_t open files,; 
/* 单 链表 容器 ， 元 素 的 类 型 是 


试 


图 创建 ， 而 创建 目录 失败 


对 此 感 兴趣 的 模块 向 其 中 添加 文件 路 


ngx_shm_zone_t 结 构 体 ， 每 个 元 素 表 示 一 块 共享 内 存 ， 共 享 内 存 将 在 第 


14 章 介绍 


*/ 
ngx_list_t shared memory; 
// 当前 进程 中 所 有 连接 对 象 的 总 数 ， 与 下 


connections 成 员 配 合 使 月 


ngx_uint_t connection_n; 


// 指向 当前 进程 中 的 所 有 连接 对 象 ， 与 


connection_n 配 合 使 用 


ngx_connection_t *connections ; 


// 指向 当前 进程 中 的 所 有 读 事 件 对 象 ， 


connection_n 同 时 表示 所 有 读 事件 的 总 数 


ngx_event_t *read events; 


// 指向 当前 进程 中 的 所 有 写 事件 对 象 ， 
事件 的 总 数 


是 


connection_n 同 时 表示 所 有 


的 


径 名 ， 


各 全 已 
寸 到 可 


致 


ngx_event_t *write_events ' 
/* 旧 的 


ngx_cycle_t 对 象 用 于 引用 上 一 个 


ngx_cycle_t 对 象 中 的 成 员 。 例 如 


Kr 
之 


ngx_init_cycle 方 法 ， 在 启动 初期 ， 需 要 建 俐 时 的 


ngx_cycle_t 对 象 保存 一 些 变 量 ， 再 调 


ngx_init_cycle 方 法 时 就 可 以 把 旧 的 


ngx_cycle_t 对 象 传 进去 ， 而 这 时 
01d_cycle 对 象 就 会 保存 这 个 前 期 的 
ngx_cycle_t 对 象 

*/ 


ngx_cycle_t *old cycle; 
// 配置 文件 相对 于 安装 目录 的 路 径 名 称 


ngx_str_t conf_file; 
/*Nginx 处 理 配 置 文件 时 需要 特殊 处 理 区 


-9 选项 携带 的 参数 


yA 


TH 
Pa 
[ey 
全 
必 
a 
洲 
香 
I 
[ay 
RS 

深 
涡 
Pl 


ngx_str_t conf_param; 


// Nginx 配 置 文件 所 在 目录 的 路 径 


ngx_str_t conf_prefix; 
// Nginx 安 装 目 录 的 路 径 


ngx_str_t prefix; 
// 用 于 进程 间 同 步 的 文件 锁 名 称 


ngx_str_t lock_file; 
// 使 


gethostname 系 统 调用 得 到 的 主机 名 


ngx_str_t hostname; 


}; 


在 构造 hgx_cycle_t 结 构 体 成 员 的 ngx_init_cycle 方 法 中 ， 上 面 所 列 出 
的 pool 内 存 池 成 员 、hostname 主 机 名 、 日 志文 件 new_log 和 log、 存 储 所 
有 路 径 的 pathes 数 组 、 共 享 内 存 、 监 听 端 口 等 都 会 在 该 方法 中 初始 化 。 


本 章 后 续 提 到 的 流程 、 方 法 中 可 以 随处 见 到 ngx_cycle_t 结 构 体 成 员 的 
河 


0 
并 
O 


8.3.3 ngx_cycle {t 文 持 的 方法 


与 ngx_cycle_t 核 心 结 构 体 相关 的 方法 实际 上 是 非常 多 的 。 例 如 ， 
每 个 模块 都 可 以 通过 init_module 、init_process 、exit_process 、 
exit_master 等 方法 操作 进程 中 独 有 的 ngx_cycle_t 结 构 体 。 然 而 ，Nginx 
的 框架 代码 中 关于 ngx_cycle_t 结 构 体 的 方法 并 不 是 太 多 ， 表 8-2 中 列 出 
了 与 ngx_cycle_t 相 关 的 主要 方法 ， 我 们 先 做 一 个 初步 的 介绍 ， 在 后 面 
的 章节 中 将 会 提 到 这 些 方 法 的 意义 。 


表 8-2 中 列 出 的 许多 方法 都 可 以 在 下 面 各 市 中 找到 。 例 如 ， 
ngx_init_cycle 方 法 的 流程 可 参照 图 8-6 中 的 第 3 步 (调用 所 有 核心 模块 的 
create_conf 方 法 ) ~ 第 8 步 (调用 所 有 模块 的 init_module 方 法 ) 之 间 的 内 
容 ，ngx_worker_process_cycle 方 法 可 部 分 参照 图 8-7 (图 8-7 中 缺少 调用 
ngx_Worker_process_init 方 法 ) ; ngx_master_process_cycle 监 控 、 管 理 


子 进 程 的 流程 可 参照 图 8-8。 


表 8-2 ngx_cycle_t 结 构 体 文 持 的 主要 方法 


方法 名 


ngx_cycle t *ngx_init cycle 
(ngx_cycle t*old_cycle) 


ngx_int t ngx_process_options 
(ngx_ cycle t *cycle) 


ngx_int t ngx _ add inherited 
sockets(ngx cycle t *cycle) 


ngx_int t ngx_open listening_ 
sockets (ngx_cycle t *cycle) 

void ngx configure listening_ 
sockets(ngx_cycle t *cycle) 

void ngx_close listening_ 

sockets(ngx cycle t *cycle) 

void ngx_master process_ 

cycle(ngx_ cycle t *cycle) 

void ngx_single_process_cycle 
(ngx_ cycle t *cycle) 


void ngx_ start worker_ 
processes (ngx cycle t *cycle, 
ngx_int tn, ngx int t type) 


old_cycle 表示 临时 的 ngx_cycle t 指 
针 ， 一般 仅 用 来 传递 ngx_cycle t 结 构 
体 中 的 配置 文件 路 径 等 参数 


cycle 通常 是 刚刚 分 配 的 ngx_cycle t 结 构 
体 指 针 ， 仅 用 于 传递 配置 文件 路 径 信息 


cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指针 


cycle 是 当前 进程 的 ngx_cycle t 结构 
体 指针 


cycle 是 当前 进程 的 ngx_cycle t 结构 
体 指针 


cycle 是 当前 进程 的 ngx_cycle + 结构 
体 指针 

cycle 是 当前 进程 的 ngx_cycle 1 结构 
体 指针 

cycle 是 当前 进程 的 ngx_cycle 【结构 
体 指针 

cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指针 , n 是 启动 子 进程 的 个 数 ，type 
是 启动 方式 ， 它 的 取 值 范围 有 以 下 5 个 : 

1) NGX PROCESS RESPAWN:; 

2) NGX PROCESS NORESPAWN; 

3) NGX PROCESS JUST SPAWN:; 

4) NGX PROCESS JUST RESPAWN:; 

5) NGX PROCESS DETACHED. 
type 的 值 将 影响 8.6 节 中 ngx_process t 结 
构 体 的 respawn、detached、just_ spawn 标 
志 位 的 值 


执行 意义 

返回 初始 化 成 功 的 完整 的 ngx_cycle_ 
1 结构 体 ， 该 函数 将 会 负责 初始 化 ngx_ 
cycle tf 中 的 数据 结构 、 解 析 配 置 文件 、 
加 载 所 有 模块 、 打 开 监 听 端 口 、 初 始 化 
进程 问 通 信 方 式 等 工作 。 如 果 失 败 . 则 
返回 NULL 空 指针 

用 运行 Nginx 时 可 能 携带 的 目录 参数 
来 初始 化 cycle， 包 括 初始 化 运行 目录 、 
配置 目录 ， 并 生成 完整 的 nginx.conf 配 
置 文件 路 径 

在 执行 不 重启 服务 升级 Nginx 的 操作 
时 ， 老 的 Nginx 进程 会 通过 环境 变量 
“NGINX” 来 传递 需要 打开 的 监听 端 
口 ， 新 的 Nginx 进程 会 通过 ngx add_ 
inherited_sockets 方法 来 使 用 已 经 打开 
的 TCP 监听 端口 

监听 、 绑 定 cycle 中 listening 动态 数 
组 指定 的 相应 端口 

根据 nginx.conf 中 的 配置 项 设置 已 经 
监听 的 句柄 

关闭 cycle 中 listening 动态 数组 已 经 
打开 的 句柄 


进入 master 进程 的 工作 循环 


进入 单 进程 模式 ( 非 master、worker 
进程 工作 模式 ) 的 工作 循环 


启动 n 个 worker 子 进程 ， 并 设置 好 
每 个 子 进程 与 master 父 进 程 之 间 使 用 
socketpair 系统 调用 建立 起 来 的 socket 
句柄 通信 机 制 


方法 名 


void ngx_start _ cache _ 
manager_proceSSes(ngX_cycle { 
*Ccycle, ngx_uint t respawn) 


void ngx pass open channel 
(ngx_cycle t *ecycle, ngx_ 
channel t *ch) 

Void ngx_signal worker_ processes 
(ngx_ cycle t *cycle, int signo) 


ngx uint t ngx reap children 
(ngx_cycle t*cycle) 


voidngx_master process exit 
(ngx_cycle t *cycle) 


void ngx worker process cycle 
(ngx_ cycle t *cycle, void *data) 


void ngx_ worker process init 
(ngx_cycle t *cycle, ngx uint t 
priority) 

void ngx worker process exit 
(ngx_cycle t *cycle) 

void ngx_ cache manager_ 
process_ cycle(ngx cycle t *cycle, 
void *data) 


void ngx_process events and 
timers (ngx_cycle t *cycle) 


cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指 针 , respawn 是 启动 子 进程 的 方式 ， 
它 与 ngx_start worker_processes 方法 中 
的 type 参数 意义 完全 相同 


cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指针 ，ch 是 将 要 向 子 进程 发 送 的 信息 
cycle 是 当前 进程 的 ngx_cycle t 结 构 


体 指针 ，signo 是 信号 


cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指 针 


cycle 是 当前 进程 的 ngx_cycle 1 结构 


体 指针 

cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指针 ， 这 里 还 未 开始 使 用 data 参数 ， 
所 以 data 一 般 为 NULL 

cycle 是 当前 进程 的 ngx_cycle 1 结构 
体 指针 ，priority 是 worker 进程 的 系统 
优先 级 

cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指针 

cycle 是 当前 进程 的 ngx cycle1t 结 
构 体 指针 ，data 是 传人 的 ngx_cache_ 
manager_ctx_t 结构 体 指针 


cycle 是 当前 进程 的 ngx_cycle t 结 构 
体 指 针 


( 续 ) 
执行 意义 

根据 是 否 使 用 文件 缓存 模块 ， 也 就 是 
cycle 中 存储 路 径 的 动态 数组 中 是 否 有 路 
径 的 manage 标志 打开 ， 来 决定 是 否 启 动 
cache manage 子 进 程 ， 同 样 根据 loader 
标志 决定 是 否 启动 cache loader 子 进程 

向 所 有 已 经 打开 的 channel( 通 过 
socketpair 生成 的 句柄 进行 通信 ) 发 送 
ch 信息 

处 理 worker 进程 接收 到 的 信号 

检查 master 进程 的 所 有 子 进程 ， 根 
据 每 个 子 进程 的 状态 ( ngx_process t 结 
构 体 中 的 标志 位 ) 判断 是 否 要 启动 子 进 
程 、 更 改 pid 文件 等 


退出 master 进程 工作 的 循环 


进入 worker 进程 工作 的 循环 


进入 worker 进程 工作 循环 之 前 的 初 
始 化 工作 


退出 worker 进程 工作 的 循环 


执行 缓存 管理 工作 的 循环 方法 。 这 与 
文件 缓存 模块 密切 相关 ， 在 本 章 中 不 做 
详细 探讨 

使 用 事件 模 坪 处 理 截 止 到 现在 已 经 收 
集 到 的 事件 。 该 函数 由 事件 模块 实现 ， 
详 见 第 9 章 


8.4 ”Nginx 局 动 时 框 染 的 处 理 流程 


通过 阅读 8.3 节 ， 读 者 应 该 对 ngx_cycle_t 结 构 体 有 了 基本 的 了 解 ， 
下 面 继续 介绍 Nginx 在 局 动 时 框架 做 了 些 什 么 。 注 意 ， 本 市 描述 的 
Nginx 局 动 流 程 基 本 上 不 包 合 Nginx 模 块 在 启动 流程 中 所 做 的 工作 ， 仪 
仅 古 展示 框架 代码 如 何 使 服务 运行 起 来 ， 这 里 的 框架 主要 束 是 调用 表 8- 
2 中 列 出 的 方法 。 


如 图 8-6 所 示 ， 这 里 包括 Nginx 框 以 在 局 动 阶段 执行 的 所 有 基本 流 
程 ， 零 俯 的 工作 这 里 不 涉及 ， 对 一 些 复杂 的 业务 也 仅 做 催 单 说 明 (如 
图 8-6 中 的 第 2 步 涉及 的 平滑 升级 的 问题 ) ， 本 节 关 注 的 重点 只 是 Nginx 
的 正 贡 局 动 流程 。 


1 ) 根据 命令 行 得 到 
配置 文件 路 径 


2 ) 如 果 处 于 升级 中 ， 则 监听 环境 
变量 里 传递 的 监听 句柄 


3 ) 调用 所 有 核心 模块 的 create_conf 方法 
生成 存放 配置 项 的 结构 体 


4) 针对 所 有 核 ， ~ 


nginx conf 配 和 图 文 


5) 调用 所 有 核心 模块 的 
init _conf 方 法 


6 ) 创 建 目录 、 打 开 文 件 、 初 始 化 共享 
内 存 等 进程 间 通 信 方 式 


7) 打 开 由 各 Nginx 模块 从 配置 文件 
中 读 取 到 的 监听 端口 


8) 调用 所 有 模块 的 
init _module 方 法 


[检测 Nginx 运 行 方式 ] 


[以 单 进程 方式 运行 Nginx] 
9) 进 入 single 模式 


| 


[以 master 多 进程 方式 运行 Nginx ] 


进入 master 模 式 


5 10) 调用 所 有 模块 的 init_process 方 法 
[多 进程 并 发 执行 ] 


14) 启动 cache manager 进 程 12) 启动 worker 进 程 


13) 调用 所 有 模块 的 init_process 方 法 


i 
1 
出 
1 
1 
i 
也 


15 ) 启动 cache loader 子 进程 


t 
TE 
| 


16) 关闭 父 进 程 启动 时 
监听 的 端口 


图 8-6 ”Nginx 启 动 过 程 的 流程 图 


下 面 位 要 介绍 一 下 图 8-6 中 的 主要 步 又 : 


1) 在 Nginx 启 动 时 ， 首 先 会 解析 命令 行 ， 处 理 各 种 参数 。 因 为 
Nginx 十 以 配置 文件 作为 核心 提供 服务 的 ， 所 以 最 主要 的 殉 是 确定 配置 
文件 nginx.conf 的 路 径 。 这 里 会 预先 创建 一 个 临时 的 ngx_cycle_t 类 型 变 
量 ， 用 它 的 成 员 存 储 配 置 文件 路 径 (实际 上 还 会 使 用 这 个 临时 
ngx_cycle_t 结 构 体 的 其 他 成 员 ， 如 log 成 员 会 指向 屏幕 输出 日 志 ) ， 最 
后 调用 表 8-2 中 的 ngx_process_options 方 法 来 设置 配置 文件 路 径 等 参数 。 


2) 图 8-6 中 的 第 2 步 实际 上 就 是 在 调用 表 8-2 中 的 
ngx_add_inherited_sockets 方 法 。Nginx 在 不 重启 服务 升级 时 ， 也 就 是 我 
们 说 过 的 平滑 升级 〈 参 见 1.9 节 ) 时 ， 它 会 不 重启 master 进 程 而 启动 新 
版 本 的 Nginx 程 序 。 这 样 ， 旧 版 本 的 master 进 程 会 通过 execve 系 统 调用 
来 启动 新 版 本 的 master 进 程 ( 先 fork 出 子 进程 再 调用 exec 来 运行 新 程 
序 ) ， 这 时 旧版 本 的 master 进 程 必须 要 通过 一 种 方式 告诉 新 版 本 的 
master 进 程 这 是 在 平滑 升级 ， 并 且 传 递 一 些 必 要 的 信息 。Nginx 是 通过 
环境 变量 来 传递 这 些 信息 的 ， 新 版 本 的 master 进 程 通过 
ngx_add_inherited_sockets 方 法 由 环境 变量 里 读 取 平 滑 升 级 信息 ， 并 对 
旧版 本 Nginx 服 务 监 听 的 句柄 做 继承 处 理 。 


3) 第 3 步 ~ 第 8 步 ， 都 是 在 ngx_init_cycle 方 法 中 执行 的 。 在 初始 化 
ngx_cycle_t 中 的 所 有 容 亏 后 ， 会 为 读 取 、 解 析 配 置 文件 做 准备 工作 。 
因为 每 个 模块 都 必须 有 相应 的 数据 结构 来 存储 配置 文件 中 的 各 配置 


项 ， 创 建 这 些 数据 结构 的 工作 都 需要 在 这 一 步 进行 。Nginx 框 架 只 关心 
NGX_CORE_MODULE 核 心 模块 ， 这 也 是 为 了 降低 框架 的 复杂 度 。 这 
里 将 会 调用 所 有 核心 模块 的 create_conf 方 法 (也 只 有 核心 模块 才 有 这 个 
方法 ) ， 这 意味 着 需要 所 有 的 核心 模块 开始 构造 用 于 存储 配置 项 的 结 
构 体 。 其 他 非 核 心 模块 怎么 办 呢 ? 其 实 很 简单 。 这 些 模块 大 都 从 属于 
一 个 核心 模块 ， 如 每 个 HTTP 模 块 都 由 ngx_http_module 管 理 (如 图 8-2 
所 示 ) ， 这 样 hgx_http_module 在 解析 自己 感 兴趣 的 “http” 配 置 项 时 ， 将 
会 调用 所 有 HTTP 模 块 约定 的 方法 来 创建 存储 配置 项 的 结构 体 (如 第 4 


hn ir \ 
草 中 介绍 过 的 xxx_create_main_ conf、XxXX_create_SrV_conf 、 


xxx_create loc_conf 方 法 ) 。 


4) 调用 配置 模块 提供 的 解析 配置 项 方法 。 裔 历 nginx.conf 中 的 所 有 
配置 项 ， 对 于 任 一 个 配置 项 ， 将 会 检查 所 有 核心 模块 以 找 出 对 它 感 兴 
趣 的 模块 ， 并 调用 该 模块 在 ngx_command_t 结 构 体 中 定义 的 配置 项 处 理 
方法 。 这 个 流程 可 以 参考 图 4-1。 


5) 调用 所 有 NGX_CORE _ MODULE 核心 模块 的 init_conf 方 法 。 这 
一 步骤 的 目的 在 于 让 所 有 核心 模块 在 解析 完 配置 项 后 可 以 做 综合 性 处 
理 。 


6) 在 之 前 核心 模块 的 init_conf 或 者 create_conf 方 法 中 ， 可 能 已 经 有 
些 模块 (如 缓存 模块 ) 在 ngx_cycle_t 结 构 体 中 的 pathes 动 态 数组 和 
open_files 链 表 中 添加 了 需要 打开 的 文件 或 者 目 孙 ， 本 步骤 将 会 创建 不 


存在 的 目录 ， 并 把 相应 的 文件 打开 。 同 时 ，ngx_cycle_t 结 构 体 的 
shared_memory 链 表 中 将 会 开始 初始 化 用 于 进程 间 通 信 的 共享 内 存 。 


7) 之 前 第 4 步 在 解析 配置 项 时 ， 所 有 的 模块 都 已 经 解析 出 自己 需 
要 监听 的 端口 ， 如 HTTP 模 块 已 经 在 解析 http{...} 配 置 项 时 得 到 它 要 监听 
的 端口 ， 并 添加 到 listening 数 组 中 了 “。 这 一 步 又 丈 是 按照 listening 数 组 
中 的 每 一 个 ngx_listening_t 元 素 设置 socket 句 柄 并 监听 端口 (实际 上 ， 这 
一 步骤 的 主要 工作 就 是 调用 表 8-2 中 的 ngx_open_listening_sockets 方 


法 ) 。 


8) 在 这 个 阶段 将 会 调用 所 有 模块 的 init_ module 方 法 。 接 下 来 将 会 
根据 配置 的 Nginx 运 行 模式 决定 如 何 工作 。 


9) 如 果 nginx.conf 中 配置 为 单 进程 工作 模式 ， 这 时 将 会 调用 
ngx_single_process_cycle 方 法 进入 单 进程 工作 模式 。 


10) 调用 所 有 模块 的 init_process 方 法 。 单 进程 工作 模式 的 启动 工作 
至 此 全 部 完成 ， 将 进入 正常 的 工作 模式 ， 也 就 是 8.5 字 和 8.6 广 分 别 介绍 
的 worker 进 程 工作 循环 、master 进 程 工作 循环 的 结合 体 。 

11) 如 果 进 入 master、worker 工 作 模 式 ， 在 启动 worker 子 进程 、 


cache manage 子 进程 、cache loader 子 进程 后 ， 丈 开始 进入 8.6 万 提 到 的 
工作 状态 ， 至 此 ，master 进 程 启动 流程 执行 完毕 。 


12) 由 masterj 进 程 按照 配置 文件 中 worker 进 程 的 数目 ， 启 动 这 些 子 
进程 (也 就 是 调用 表 8-2 中 的 ngx_start_worker_processes 方 法 ) 。 


13) 调用 所 有 模块 的 init_process 方 法 。worker 进 程 的 启动 工作 至 此 
全 部 完成 ， 接 下 来 将 进入 正常 的 循环 处 理事 件 流程 ， 也 就 是 8.5 广 中 介 
绍 的 worker 进 程 工作 循环 的 ngx_worker_process_cycle 方 法 。 


14) 在 这 一 步骤 中 ， 由 master 进 程 根据 之 前 各 模块 的 初始 化 情况 来 
决定 是 否 启动 cache manage 子 进程 ， 也 就 是 根据 ngx_cycle_t 中 存储 路 径 
的 动态 数组 pathes 中 是 否 有 某 个 路 径 的 manage 标 志 位 打开 来 决定 是 否 启 
动 cache manage 子 进程 。 如 果 有 任何 1 个 路 径 的 manage 标 志 位 为 1， 则 启 
动 cache manage 子 进程 。 


15) 与 第 14 步 相同 ， 如 果 有 任何 1 个 路 径 的 loader 标 志 位 为 1， 则 启 
动 cache loader 子 进程 。 对 于 第 14 步 和 第 15 步 而 言 ， 都 是 与 文件 绥 存 模 
块 密切 相关 的 ， 但 本 章 不 会 详 述 。 


16) 关闭 只 有 worker 进 程 才 需要 监听 的 端口 。 


在 以 上 16 个 步骤 中 ， 人 简要 地 列举 出 了 Nginx 在 单 进程 模式 和 master 
工作 方式 下 的 局 动 流程 ， 这 里 仅 列举 出 与 Nginx 框 以 密切 相关 的 步 桑 ， 
并 未 涉及 具体 的 模块 。 


8.5“ worker 进程 是 如 何 工 作 的 


本 厄 的 内 容 不 会 涉及 事件 模块 的 处 理工 作 ， 只 是 探讨 在 worker 进 程 
中 循环 执行 的 ngx_worker_process_cycle 方 法 是 如 何 控制 进程 运行 的 。 


master 进 程 如 何 通知 workerj 进 程 停止 服务 或 更 换 日 志文 件 呢 ? 对 于 
这 样 控制 进程 运行 的 进程 间 通 信 方 式 ，Nginx 采 用 的 是 信号 ( 详 见 14.5 
节 ) 。 因 此 ，worker 进 程 中 会 有 一 个 方法 来 处 理 信 号 ， 它 就 是 


ngx_signal_handler 方 法 。 


void ngx_signal handler(int signo) 


对 于 worker 进 程 的 工作 方法 ngx_worker_process_cycle 来 说 ， 它 
注 以 下 4 个 全 局 标志 位 。 


小 
沙 


sig atomic t ngx_terminate 
sig atomic t ngx_quit; 
ngx_uint_t ngx_exiting; 
sig atomic t ngx_reopen,; 


其 中 的 ngx_terminate、ngx_quit、ngx_reopen 都 将 由 
ngx_signal_handler 方 法 根据 接收 到 的 信号 来 设置 。 例 如 ， 当 接收 到 
QUIT 信 号 时 ，ngx_quit 标 志 位 会 设 为 1， 这 是 在 告诉 worker 进 程 需要 优 
雅 地 关闭 进程 ， 当 接收 到 TERM 信 号 时 ，ngx_terminate 标 志 位 会 设 为 
1， 这 是 在 告诉 worker 进 程 需 要 强制 关闭 进程 ， 当 接收 到 USR1 信 号 时 ， 


ngx_reopen 标 志 位 会 设 为 1， 这 是 在 告诉 Nginx 需 要 重新 打开 文件 〈 如 切 
换 日 志文 件 时 ) ， 见 表 8-3。 


表 8-3 ”worker 进 程 接收 到 的 信号 对 框架 的 意义 


信 号 对 应 进程 中 的 全 局 标志 位 变量 意 义 
RT ngx_quit 优雅 地 关闭 进程 


TERM 或 INT 强制 关闭 进程 
ET 有 


ngx_exiting 标 志 位 仪 由 ngx_worker_process_cycle 方 法 在 退出 时 作为 
标志 位 使 用 ， 如 图 8-7 所 示 。 


、 [ngxexiting 标志 位 为 1, 进程 退出 ] 


对 当前 所 有 活动 连接 调用 读 事件 
方法 处 理 关闭 连接 事件 


[还 有 未 处 理 完 的 事件 ] 如 
[所 有 连接 都 已 关闭 ] 


[ngx reopen 为 0] 调用 所 有 模块 的 


[ngxterminate 标 志 位 为 1, 强制 结束 进程 ] 


exit proces 咏 法 


[ngx_terminate 为 0] 


人 标志 位 为 1 ,优雅 地 关闭 进程 ] 


Vy 
[ngx_quit 为 0] War Tt 设置 ) 销毁 
内 存 池 


| 一人 < 


[ngx_reopen 标志 位 为 1, 重新 打开 所 有 文件 ] ® 


重新 打开 
所 有 文件 


图 8-7” worker 进程 正常 工作 、 退 出 时 的 流程 图 


在 ngx_worker_process_cydle 方 法 中 ， 通 过 检查 ngx_exiting 、 


ngX_terminate、ngx_quit、ngx_reopen 这 4 个 标志 位 来 决定 后 续 动 作 。 


如 果 ngx_exiting 为 1， 则 开始 准备 天 财 worker 进 程 。 甫 先 ， 根 据 当 
前 ngx_cycle_t 中 所 有 正在 处 理 的 连接 ， 调 用 它们 对 应 的 关闭 连接 处 理 
方法 〈 就 是 将 连接 中 的 close 标 志 位 置 为 1， 再 调用 读 事件 的 处 理 方 法 ， 
在 第 9 章 中 会 详细 讲解 Nginx 连 接 ) 。 调 用 所 有 活动 连接 的 读 事件 处 理 
方法 处 理 连 接 关 闭 事件 后 ， 将 检查 ngx_event_timer_rbtree 红 黑 树 (保存 
所 有 事件 的 定时 器 ， 在 第 9 章 中 会 介绍 它 ) 是 否 为 裤 ， 如 果 不 为 空 ， 表 
示 还 有 事件 需要 处 理 ， 将 继续 向 下 执行 ， 调 用 
ngx_process_events_and_timers 方 法 处 理事 件 ， 如果 为 衬 ， 表 示 已 经 处 
理 完 所 有 的 事件 ， 这 时 将 调用 所 有 模块 的 exit_process 方 法 ， 最 后 请 虹 
内 存 池 ， 退 出 整个 worker 进 程 。 


@ 注意 ngx_exiting 标 志 位 只 有 唯一 段 代码 会 设置 它 ， 也 就 是 
下 面 接收 到 QUIT 信 号 。ngx_quit 只 有 在 首次 设置 为 1 时 ， 才 会 将 
ngX_exiting 置 为 1。 


如 果 ngx_exiting 不 为 1， 那 么 调用 ngx_process_events_and_timers 方 
法 处 理事 件 。 这 个 方法 是 事件 模块 的 核心 方法 ， 将 会 在 第 9 章 介绍 它 。 


接 下 来 检查 ngx_terminate 标 志 位 ， 如 有 果 ngx_terminate 不 为 1， 则 继 
续 向 下 检查 ， 否 则 开始 准备 退出 worker 进 程 。 与 上 一 步 ngx_exiting 为 1 
的 退出 流程 不 同 ， 这 里 不 会 调用 所 有 活动 连接 的 处 理 方法 去 处 理 天 闭 
连接 事件 ， 也 不 会 检查 是 否 已 经 处 理 完 所 有 的 事件 ， 而 是 立刻 调用 所 
有 模块 的 exit_process 方 法 ， 销 毁 内 存 池 ， 退 出 worker 进 程 。 


接 下 来 再 检查 ngx_quit 标 志 位 ， 如 果 标 志 位 为 1， 则 表示 需要 优雅 
地 关闭 连接 。 这 时 ，Nginx 首 先 会 将 所 在 进程 的 名 字 修 改 为 “worker 
process is shutting down”， 然 后 调用 ngx_close_jlistening_sockets 方 法 来 关 
闭 监 听 的 端口 ， 接 着 设置 ngx_exiting 标 志 位 为 1， 继 续 辐 下 执行 (检查 


ngx_reopen_files 标 志 位 ) 
最 后 检查 ngx_reopen 标 志 位 ， 如 果 为 1， 则 表示 需要 重新 打开 所 有 


文件 。 这 时 ， 调 用 ngx_reopen_files 方 法 重新 打开 所 有 文件 。 之 后 继续 
下 一 个 循环 ， 再 去 检查 ngx_exiting 标 志 位 。 


8.6 ”master 进 程 是 如 何 工 作 的 


master 进 程 不 需要 处 理 网 络 事件 ， 它 不 负责 业务 的 执行 ， 只 会 通过 
管理 worker 等 子 进 程 来 实现 重启 服务 、 平 滑 升 级 、 更 换 日 志文 件 、 配 置 
文件 实时 生殖 等 功能 。 与 8.5 世 类 似 的 是 ， 它 会 通过 检查 以 下 7 个 标志 位 


来 决定 ngx_master_process_cycle 方 法 的 运行 。 


sig_atomic ngx_reap; 
sig_atomic ngx_terminate; 
sig_atomic ngx_quit; 


sig_atomic 
sig_atomic 
sig_atomic 
sig_atomic 


ngx_reconfigure; 
ngx_reopen; 
ngx_change_binary; 
ngx_noaccept; 


cr rr rr rr rt rr 中 


ngx_si gnal_handler 方 法 会 根据 接收 到 的 信号 设置 ngx_reap 
ngx_quit ~ ngx_terminate ~ ngx_reconfigure 、 ngx_reopen 、 


ngx_change_binary、 ngx_noaccept 这 些 标 志 位 ， 见 表 8-4。 


表 8-4 ”进程 中 接收 到 的 信号 对 Nginx 框 架 的 意义 


对 应 进程 中 的 


训 
«< 


全 局 标志 位 变量 
QUIT 优雅 地 关闭 整个 服务 
TERM 或 者 INT 强制 关闭 整个 服务 
USR1 重新 打开 服务 中 的 所 有 文件 


所 有 子 进 程 不 再 接受 处 理 新 的 连接 ， 实 际 相当 于 对 所 有 的 子 进 程 
WINCH ngx noaccept i , . ~ i ~ 入 | 
发 送 QUIT 信号 量 


USR2 平滑 升级 到 新 版 本 的 Nginx 程序 


HUP 重读 配置 文件 并 使 服务 对 新 配置 项 生效 


有 子 进程 意外 结束 ， 这 时 需要 监控 所 有 的 子 进程 ， 也 就 是 ngx_ 
CHLD ngx reap a 
reap_children 方法 所 做 的 工作 


表 8-4 列 出 了 master 工 作 流 程 中 的 7 个 全 局 标志 位 变量 。 除 此 之 外 ， 
还 有 一 个 标志 位 也 会 用 到 ， 它 仅仅 是 在 master 工 作 流 程 中 作为 标志 位 使 
用 的 ， 与 信号 无 天 。 


ngx_uint_t ngx_restart; 


在 解释 master 工 作 流 程 前 ， 还 需要 对 master 进 程 管 理子 进程 的 数据 
结构 有 个 初步 了 解 。 Wa on 虽然 子 进程 中 
也 会 有 ngx_processes 数 组 ， 但 这 个 数组 仪 仅 是 给 master 进 程 使 用 的 。 下 
面 看 一 下 ngx_processes 全 局 数组 的 定义 ， 代 码 如 下 。 


// 定义 


1024 个 元 素 的 


CC 


ngx_processes 数 组 ， 也 就 是 最 多 只 能 有 


1024 个 子 进 程 


#define NGX_MAX_PROCESSES 1024 
// 当前 操作 的 进程 在 


ngx_processes 数 组 中 的 下 标 


ngx_int_t ngx_process_Slot 
// ngx_processes 数 组 中 有 意义 的 


ngx_process_t 元 素 中 最 大 的 下 标 


ngx_int_t ngx_last_process; 


// 存储 所 有 子 进程 的 数组 


ngx_process_t ngx_processes[NGX MAX_ PROCESSES]; 


master 进 程 中 所 有 子 进程 相关 的 状态 信息 都 保存 在 ngx_processes 数 
组 中 。 再 来 看 一 下 数组 元 素 的 类 型 ngx_process_t 结 构 体 的 定义 ， 代 码 如 
ee 


typedef struct { 
// 进程 


ID 
ngx_pid t pid; 
// 由 


waitpid 系 统 调 用 获取 到 的 进程 状态 


int _ Status ， 
全 这 是 


socketpair 系 统 调 用 产生 出 的 用 于 进程 间 通 信 的 


socket 人 句柄 ， 这 一 对 


socket 人 句柄 可 以 互相 通信 ， 目 前 用 了 
程 与 


进 
worker 子 进程 间 的 通信 ， 详 见 


master 父 


14 .4 节 


*/ 
ngx_socket_t channel[2]; 


// 子 进 程 的 循环 执行 方法 ， 当 父 进程 调 


ngx_spawn_process 生 成 子 进程 时 使 


ngx_spawn_proc_pt proc; 


/* 上 面 的 
ngx_spawn_proc_pt 方 法 中 第 
2 个 参数 需要 传递 


1 个 指针 ， 它 是 可 选 的 。 例 如 ， 


worker 子 进程 就 不 需要 ， 而 


cache manage 进 程 就 需要 
ngx_cache_manager_ctx 上 下 文成 员 。 这 时 ， 


data 一 般 与 


ngx_spawn_proc_pt 方 法 中 第 


2 个 参数 是 等 价 的 


*/ 
void *data 


// 进程 名 称 。 : 操作 系统 中 显示 的 进程 名 称 与 


name 相 同 


char *name; 
// 标志 位 ， 为 


1 时 表示 在 重新 生成 子 进程 


unsigned respawn:1; 
// 标志 位 ， 为 


1 时 表示 正在 生成 子 进程 


unsigned just_spawn:1; 
// 标志 位 ， 为 


1 时 表示 在 进行 父 、 子 进程 分 离 


unsigned detached:1; 
// 标志 位 ,为 


1 时 表示 进程 正在 退出 


unsigned exiting:1; 
// 标志 位 ， 为 


1 时 表示 进程 已 经 退出 


unsigned exited:1; 
} ngx_process_t,; 


master 进 程 怎 样 启动 一 个 子 进程 呢 ? 其 实 很 简单 ，fork 系 统 调用 即 
可 以 完成 。ngx_spawn_ 0 去 封装 了 fork 系 统 调用 ， 并 且 会 从 
ngx_processes 数 组 中 选择 一 个 还 未 使 用 的 ngx_process_t 元 素 存储 这 个 子 
进程 的 相关 信息 。 如 果 所 有 1024 个 数组 元 素 中 已 经 没有 空余 的 元 素 ， 
也 就 是 说 ， 子 进程 个 数 超过 了 最 大 值 1024， 那 么 将 会 返回 


NGX_INVALID_PID。 因 此 ，ngx_processes 数 组 中 元 素 的 初始 化 将 在 


ngx_spawn_process 方 法 中 进行 。 


下 面 对 局 动 子 进程 的 方法 做 一 个 简单 说 明 ， 它 的 定义 如 下 。 


ngx_pid_t ngx_spawn_process(ngx_cycle t *cycle，ngx_spawn_proc_pt proc, void 
*data, char *name, ngx_int_t respawn) 


这 里 的 proc 函 数 指针 束 是 子 进 程 中 将 要 执行 的 工作 循环 。 下 面 看 一 
下 ngx_spawn_proc_pt 的 定义 ， 代 码 如 下 。 


typedef void (*ngx_spawn_proc_pt) (ngx_cycle t *cycle, void *data) ， 


因此 ，worker 进 程 的 工作 循环 ngx_worker_process_cycle 方 法 也 是 依 
照 ngx_spawn_proc_pt 来 定义 的 ， 代 码 如 下 。 


static void ngx_worker_process_cycle(ngx_cycle_t *cycle, void *datal) 


cache manage 进 程 或 者 cache loader 进 程 的 工作 循环 
ngx_cache_manager_process_cycle 方 法 也 是 如 此 ， 代 码 如 下 。 


static void ngx_cache manager_process _ cycle(ngx_cycle t *cycle, void *data); 


/DA 


那么 ，ngx_processes 数 组 中 这 些 进程 的 状态 是 怎么 改变 的 呢 ? 依靠 
信号 ! 当 每 个 子 进 程 意外 退出 时 ，master 父 进程 会 接收 到 Linux 内 核发 
来 的 CHLD 信 号 ， 而 处 理 信号 的 ngx_signal_handler 方 法 这 时 将 会 做 以 下 


处 理 : 将 sig_reap 标 志 位 置 为 1， 调 用 ngx_process_get_status 方 法 修改 
ngx_processes 数 组 中 所 有 子 进 程 的 状态 (通过 waitpid 系 统 调用 得 到 意外 
结束 的 子 进程 ID ， 然 后 遍历 ngx_processes 数 组 找到 该 子 进程 ID 对 应 的 
ngx_process_t 结 构 体 ， 将 其 exited 标 志 位 置 为 1) 。 那 么 ， 一 个 子 进程 意 
外 结束 后 ， 如 何 局 动 新 的 子 进程 呢 ? 这 可 以 在 图 8-8 所 示 的 master 进 程 
的 工作 循环 中 找到 答案 。 


[ngx_reap 标 志 位 为 1] 


1 ) 监 控 子 进程 , 若 所 有 子 进 程 


和 已 退出 则 返回 的 live 为 0 


[ive 标 志 位 为 0, 同时 ngx_terminate 或 者 ngx_quit 标志 位 为 1] 


PEA 


6) 同 所 有 子 进程 发 送 
TERM 信号 
[ngx terminate 标 志 位 为 1, 强制 关闭 服务 ] 》 


2 ) 删 除 存 储 master 
进程 号 的 pid 文 件 


《7 


7 向 所 有 子 进程 发送 [ngx terminate 为 0] 3) 调 用 所 有 楼 也 的 
OUIT 作 exit_master 方 法 
[ngx_quit 标志 位 为 1， 
优雅 地 关闭 服务 | 4) 关 闭 所 有 
网 TT 
8) 关 闭 所 看 [ngx _qguit 为 0] 监听 端口 
监听 端口 
5) 销 毁 内 存 池 
[ngx_reconfigure 标志 位 为 1] CS 
[ngx _reconfigure 为 0] 
9) 重 新 读 取 ® 
配置 文件 es 1] 13) EE 
worker 子 进程 
10) 启动 worker 
子 进程 ce 
[ngx_restart 为 0] 14) 启动 cache manage 
11) 启动 cache manage 
子 进 程 


[ngx_reopen 标志 位 为 由 /一 15) 重 新 打开 
开 有 文 作 


12) 向 所 有 子 进程 发 送 


QUIT 信 号 


[ngx_reopen 为 0] 


[ngx_change _binary 标 志 位 为 1] 
17) 运 行 新 的 Nginx 
hl 件 


二 进 制 文 


[ngx_change_binary 为 0] 
[ngx_noaccept 标志 位 为 1] 


18) 向 所 有 子 进程 发 送 


QUIT 信 号 要 求 关 闭 服务 


图 8-8 ”master 进 程 的 工作 循环 


下 面 人 简要 介绍 一 下 图 8-8 中 列 出 的 流程 。 实 际 上 ， 根 据 以 下 8 个 标志 
fy: ngx reap ~ ngx_ terminate ~ ngx_quit 、 ngx_reconfigure 、 
ngx_restart、ngx_reopen、ngx_change_binary、ngx_noaccept， 决 定 执 行 
不 同 的 分 支流 程 ， 并 循环 执行 (注意 ， 每 次 一 个 循环 执行 完毕 后 进程 
会 被 挂 起 ， 直 到 有 新 的 信号 才 会 激活 继续 执行 ) 。 


1) 如 果 ngx_reap 标 志 位 为 0， 则 继续 向 下 执行 第 2 步 ， 如 果 
ngx_reap 标 志 位 为 1， 则 表示 需要 监控 所 有 的 子 进程 ， 同 时 调用 表 8-2 中 
的 ngx_reap_children 方 法 来 管理 子 进 程 。 这 时 ，ngx_reap_children 方 法 
将 会 授 历 ngx_processes 数 组 ， 检 查 每 个 子 进 程 的 状态 ， 对 于 非 正常 退出 
的 子 进程 会 重新 拉 起 。 最 后 ，ngx_processes 方 法 会 返回 一 个 live 标 志 
位 ， 如 果 所 有 的 子 进 程 都 已 经 正常 退出 ， 那 么 live 将 为 0， 除 此 之 外 ， 


live 会 为 1 。 


2) 当 ]ive 标 志 位 为 0 (所 有 子 进程 已 经 退出 ) 、ngx_terminate 标 志 
位 为 1 或 者 ngx_quit 标 志 位 为 1 时 ， 都 将 调用 ngx_master_process_exit 方 法 
开始 退出 master 进 程 ， 否 则 继续 向 下 执行 第 6 步 。 在 
ngx_master_process_exit 方 法 中 ， 百 移 会 删除 存储 进程 号 的 pid 文 件 。 


3) 继续 之 前 的 ngx_master_process_exit 方 法 ， 调 用 所 有 模块 的 


exit_ master 方 法 。 


4) 调用 ngx_close_listening_sockets 方 法 关闭 进程 中 打开 的 监听 端 


5) 销毁 内 存 池 ， 退 出 masterj 进 程 。 


6) 如 果 ngx_terminate 标 志 位 为 1， 则 向 所 有 子 进程 发 送信 和 号 
TERM， 通 知 子 进程 强制 退出 进程 ， 接 下 来 直接 跳 到 第 1 步 并 挂 起 进 
程 ， 等 待 信号 激活 进程 。 如 果 ngx_terminate 标 志 位 为 0， 则 继续 执行 第 7 
i 


7) 如 果 ngx_quit 标 志 位 为 0， 跳 到 第 9 步 ， 否 则 表示 需要 优雅 地 退 
出 服务 ， 这 时 会 同 所 有 子 进程 发 送 QUIT 信 号 ， 通 知 它们 退出 进程 。 


8) 继续 ngx_quit 为 1 的 分 文 流程 。 关 闭 所 有 的 监听 端口 ， 接 下 来 直 
接 跳 到 第 1 步 并 挂 起 master 进 程 ， 等 竺 信号 激活 进程 。 


9) 如 果 ngx_reconfigure 标 志 位 为 0， 则 跳 到 第 13 步 检查 ngx_restart 
标志 位 。 如 果 ngx_reconfigure 为 1， 则 表示 需要 重新 读 取 配置 文件 。 
Nginx 不 会 再 让 原先 的 worker 等 子 进程 再 重新 读 取 配置 文件 ， 它 的 策略 
是 重新 初始 化 ngx_cycle_t 结 构 体 ， 用 它 来 读 取 新 的 配置 文件 ， 再 拉 起 
新 的 worker 进 程 ， 销 毁 旧 的 worker 进 程 。 本 步 中 将 会 调用 ngx_init_cycle 
方法 重新 初始 化 ngx_cydle_t 结 构 体 。 


10) 接 第 9 步 ， 调 用 ngx_start_worker_processes 方 法 再 拉 起 一 批 
worker 进 程 ， 这 些 worker 进 程 将 使 用 狐 ngx_cycle_t 结 构 体 。 


11) 接 第 10 步 ， 调 用 ngx_start_cache_manager_processes 方 法 ， 按 照 
缓存 模块 的 加 载 情 况 决 定 是 否 拉 起 cache manage 或 者 cache loader 进 程 。 
在 这 两 个 方法 调用 后 ， 肯 定 是 存在 子 进 程 了 了， 这 时 会 把 live 标 志 位 置 为 
1 (第 2 步 中 曾 用 到 此 标志 ) 。 


12) 接 第 11 步 ， 向 原先 的 (并非 刚刚 拉 起 的 ) 所 有 子 进程 发 送 
QUIT 信 号 ， 要 求 它们 优雅 地 退出 目 己 的 进程 。 


13) 检查 ngx_restart 标 志 位 ， 如 果 为 0， 则 继续 第 15 步 ， 检 查 
ngx_reopen 标 志 位 。 如 果 ngx_restart 为 1， 则 调用 
ngX_start worker_processes 方 法 拉 起 workerj 进 程 ， 同 时 将 ngx_restart 置 为 


05° 


14) 接 13 步 ， 调 用 ngx_start_cache_manager_processes 方 法 根据 缓存 
模块 的 情况 选择 是 否 启 动 cache manage 进 程 或 者 cache loader 进 程 ， 同 时 
将 live 标 志 位 置 为 1 。 


15) 检查 ngx_reopen 标 志 位 ， 如 果 为 0， 则 继续 第 17 步 ， 检 查 
ngx_change_binary 标 志 位 。 如 果 ngx_reopen 为 1， 则 调用 
ngx_reopen_files 方 法 重新 打开 所 有 文件 ， 同 时 将 ngx_reopen 标 志 位 置 为 
0 O 


16) 向 所 有 子 进程 发 送 USR1 信 号， 要 求 子 进程 都 得 重新 打开 所 有 
区 人 


17) 检查 ngx_change_binary 标 志 位 ， 如 果 ngx_change_binary 为 1， 
则 表示 需要 平滑 升级 Nginx， 这 时 将 调用 ngx_exec_new_binary 方 法 用 新 
的 子 进程 启动 新 版 本 的 Nginx 程 序 ， 同 时 将 ngx_change_binary 标 志 位 置 
为 0。 


18) 检查 ngx_noaccept 标 志 位 ， 如 果 ngx_noaccept 为 0， 则 继续 第 1 
步 进 行 下 一 个 循环 ， 如 果 ngx_noaccept 为 1， 则 向 所 有 的 子 进程 发 送 
QUIT 人 信号， 要求 它们 优雅 地 关闭 服 务 ， 同 时 将 ngx_noaccept 置 为 0， 并 
将 ngx_noaccepting 置 为 1， 表 示 正 在 停止 接受 新 的 连接 。 


注意 ， 在 以 上 18 个 步骤 组 成 的 循环 中 ， 并 不 是 不 停 地 在 循环 执行 
以 上 步骤 ， 而 是 会 通过 sigsuspend 调 用 使 master 进 程 休眠 ， 等 待 masterj 埋 
程 收 到 信号 后 激活 master 进 程 继续 由 上 面 的 第 1 步 执行 循环 。 


8.7 ngx_pool_t 内 存 池 


在 说 明 其 设计 前 先 来 看 看 与 ngx_pool_t 内 存 池 相关 的 15 个 方法 ， 如 
表 8-5 所 示 。 


表 8-5 内存 池 操 作 方 法 

方法 类 型 

创建 内 存 池 ， 注 意 它 的 size 参数 并 不 等 同 于 可 分 配 空间 ， 
它 同时 包含 了 管理 结构 的 大 小 ， 这 意味 着 : size 绝 不 能 小 于 
sizeof ( ngx_pool t)， 和 否则 就 会 有 内 存 越 界 错误 。 通 常 ， 可 以 
设 size 为 NGX _ DEFAULT POOL SIZE， 该 安 目 前 为 16KB， 
不 用 担心 16KB 会 不 够 用 ， 当 这 第 一 个 16KB 用 完 时 ， 会 自动 
再 分 配 16KB 内 存 的 

销毁 内 存 池 ， 它 同时 会 把 通过 该 pool 分 配 出 的 内 存 释 放 ， 
ngx_destroy_pool 而 且 ， 还 会 执行 通过 ngx_pool cleanup_add 方 法 添加 的 各 类 
资源 清理 方法 

重 置 内 存 池 ， 即 将 内 存 池 中 的 原 有 内 存 释放 后 继续 使 用 
ngx_reset_pool 这 个 方法 的 实现 是 , 会 把 大 块 内 存 释 放 给 操作 系统 ， 而 小 块 
内 存 则 在 不 释放 的 情况 下 复 用 


ngx create_ pool 


内 存 池 操作 


十 


( 续 ) 
方法 类 型 意义 
分 配 地 址 对 齐 的 内 存 。 按 总 线 长 度 (例如 sizeof ( unsigned 
ngx_palloc long)) 对 齐 地 址 后 ， 可 以 减少 CPU 读 取 内 存 的 次 数 ， 当 然 代 
价 是 有 一 些 内 存 浪费 


ITTTETTTIE 


ES 分 配 出 地 址 对 齐 的 内 存 后 ， 再 调用 memset 将 这 些 内 存 全 部 
ngx_pcalloc 

. 清 0 

基于 内 存 池 的 


分 配 、 释 放 内 存 按 参 数 atignment 进行 泡 址 对 讲 来 分 配 册 椰 ， 注意 ， 这 样 分 
Me i 配 出 的 内 存 不 管 申请 的 size 有 多 小 ， 都 是 不 会 使 用 小 块 内 存 

SS 池 的 ， 它 会 从 进程 的 堆 中 分 配 内 存 ， 并 挂 在 大 块 内 存 组 成 的 
large 单 链表 中 


提前 释放 大 块 内 存 。 它 的 效率 不 高 ， 其 实现 是 遍历 large 链 
表 ， 寻 找 ngx_pool large t 的 alloc 成 员 等 于 待 释放 地 址 ， 找 
ngx_pfree 
ee 到 后 释放 内 存 给 操作 系统 ， 将 ngx_pool large t 移 出 链表 并 
删除 


添加 一 个 需要 在 内 存 池 释放 时 同步 释放 的 资源 。 该 方法 会 
返回 一 个 ngx_pool_cleanup 1 结构 体 ， 而 我 们 得 到 后 需要 设置 
ngx_pool_cleanup t 的 handler 成 员 为 释放 资源 时 执行 的 方法 。 
ngx_ pool cleanup add ngx_pool_cleanup_add 有 一 个 参数 size， 当 它 不 为 0 时 ,会 分 
配 size 大 小 的 内 存 ， 并 将 ngx_pool_cleanup t 的 data 成 员 指 
问 该 内 存 ， 这 样 可 以 利用 这 段 内 存 传递 参数 ， 供 释放 资源 的 


随 闭 内 存 池 释 方法 使 用 。 当 size 为 0 时 ，data 将 为 NULL 
放 同 步 释放 资源 在 内 存 池 释 放 前 ， 如 果 需 要 提前 关闭 文件 (当然 是 调用 过 


ngx_pool_cleanup_ add 添加 的 文件 ， 同 时 ngx_pool_ cleanup_ 
t 的 handler 成 员 被 设 为 ngx pool cleanup file)， 则 调用 该 
方法 

以 关闭 文件 来 释放 资源 的 方法 ， 可 以 设置 到 ngx_pool_ 
cleanup t 的 handler 成 员 


以 删除 文件 来 释放 资源 的 方法 ， 可 以 设置 到 ngx_pool_ 
ngx_pool_delete file a 
cleanup {的 handler 成 员 


i 从 操作 系统 中 分 配 内 在 
| ngx_ealloe | 从 操作 系统 中 分 配 出 内 存 ， 再 调用 memset 把 内 存 清 0 
的 分 配 、 释 放 操作 | 一 


秋 放 内 存 到 操作 系统 


的 操作 


ngx_pool run cleanup file 


ngx_pool cleanup file 


Nginx 已 经 提供 封装 了 malloc、free 的 ngx_alloc、ngx_free 方 法 ， 为 
什么 还 需要 一 个 挺 复杂 的 内 存 池 呢 ? 对 于 没有 垃 圾 回收 机 制 的 C 语 言 编 
写 的 应 用 来 说 ， 最 容易 犯 的 错 就 是 内 存 泄露 。 当 分 配 内 存 与 释放 内 存 


的 逻辑 相距 遥远 时 ， 还 很 容易 发 生 同 一 块 内 存 被 释放 两 次 。 内 存 池 束 
征 为 了 降低 程序 员 犯 错 儿 率 的 : 模块 开发 者 只 需要 关心 内 存 的 分 配 ， 
而 释放 则 区 由 内 存 池 来 负责 。 


那么 ，ngx_pool_t 内 存 池 什么 时 候 会 释放 内 存 昵 ? 一 般 地 ， 内 存 池 
销毁 时 才 会 将 内 存 释放 回 操作 系统 〈 例 外 就 是 表 8-5 中 的 ngx_pfree 方 
法 ) 。 在 一 个 内 存 池 上 ， 可 以 任意 次 的 申请 内 存 ， 不 用 释放 它们 ， 唯 
一 要 做 的 就 是 记得 销毁 内 存 池 。 这 一 策略 在 降低 程序 员 们 出 错 概率 的 
同时 ， 引 入 了 男 一 问题 ， 如 果 这 个 内 存 池 的 生命 周期 很 长 ， 而 每 一 块 
内 存 的 生命 周期 很 短 ， 早 期 申请 的 内 存 会 一 直 无 谓 地 占用 着 珍贵 的 内 
存 资源 ， 这 不 是 造成 严重 的 内 存 浪费 吗 ? 比如 生成 内 存 池 后 1 天 后 销毁 
它 ， 这 1 天 中 每 秒 申 请 1K 的 内 存 ， 而 申请 到 的 每 块 内 存在 这 一 秒 中 就 已 
经 使 用 完毕 ， 这 样 1 天 结束 时 这 个 内 存 池 已 经 占用 了 86MB 的 内 存 ! 没 
错 ， 如 果 内 存 与 内 存 池 的 生命 周期 是 如 此 差异 ， 那 么 这 个 问题 是 存在 
的 。 所 以 ， 一 般 性 的 应 用 中 没有 见 过 这 样 的 内 存 池 设计 。 但 是 
ngx_pool t 内 存 池 却 可 以 应 用 在 Nginx 上 ， 这 是 因为 Nginx 是 一 个 很 纯粹 
的 Web 服务 器 ， 与 客户 端的 每 一 个 TCP 连 接 有 明确 的 生命 周期 ，TCP 连 
接 上 的 每 一 个 HTTP 请 求 有 非常 短暂 的 生命 周期 ， 如 果 每 个 请 求 、 连 接 
都 有 各 自 的 内 存 池 ， 而 模块 开发 者 们 评估 待 申请 内 存 的 使 用 周期 ， 如 
果 隶 属于 一 个 HITTP 请 求 ， 则 在 请 求 的 内 存 池 上 分 配 内 存 ， 如 果 隶 属于 
一 个 连接 ， 则 在 连接 的 内 存 池 上 分 配 内 存 ， 如 果 一 直 伴随 着 模块 ， 则 
可 以 在 ngx_conf t 的 内 存 池上 分 配 内 存 。 似 乎 我 们 得 到 了 不 用 释放 内 存 


的 好 处 ， 却 增加 了 关心 内 存 生 命 周 期 的 额外 工作 ? 事实 不 是 这 样 的 ， 
绝 大 多 数 模 块 都 在 单纯 的 处 理 请 求 ， 只 需要 使 用 ngx_http_request_t 中 的 
内 存 池 即 可 。 


ngx_pool t 内 存 池 的 设计 上 还 考虑 到 了 小 块 内 存 的 频繁 分 配 在 效率 
上 有 提升 空间 ， 以 及 内 存 碎片 还 可 以 再 减少 些 。 在 讨论 其 实现 前 ， 先 
定义 什么 叫 小 块 内 存 ，NGX_MAX_ALLOC_FROM_POOL 宏 是 一 个 很 
重要 的 标准 : 


#define NGX MAX_ALLOC_FROM POOL (ngx_pagesize - 1) 


可 见 ， 在 X86 架构 上 就 是 4095 字 市 。 通 常 ， 小 于 等 于 
NGX_MAX_ALLOC_FROM_POOL 就 意味 着 小 块 内 存 。 这 并 不 是 绝对 
的 ， 当 调用 ngx_create_pool 创 建 内 存 池 时 ， 如 果 传 递 的 size 人 参数 小 于 
NGX_MAX_ALLOC_FROM_POOL+sizeof(ngx_pool_t)， 则 对 于 这 个 内 
存 池 来 说 ，size-sizeof(ngx_pool_t) 字 节 束 是 小 块 内 存 的 标准 。 大 块 内 存 
与 小 块 内 存 的 处 理 很 不 一 样 ， 看 看 ngx_pool t 的 定义 就 知道 了 : 


typedef struct ngx_pool s ngx_pool_t; 
struct ngx_pool s { 


// 描述 小 块 内 存 池 。 当 分 配 小 块 内 存 时 ， 剩 余 的 预 分 配 空间 不 足 时 ， 会 再 分 配 


1 


ngx_pool_t, 


// 它们 会 通过 


d 中 的 


next 成 员 构 成 单 链表 


ngx_pool_data_t d 
// 评估 申请 内 存 属于 小 块 还 是 大 块 的 标准 


size_t 


max; 
// 多 个 小 块 内 存 池 构 成 链表 时 ， 
current 指 向 分 配 内 存 时 遍历 的 第 


1 个 小 块 内 存 六 


区 


ngx_pool_t *current; 
XA 


ngx_output_chain, 与 内 存 池 关系 不 大 ， 了 略 过 


ngx_chain_t *chain; 


// 大 块 内 存 都 直接 从 进程 的 堆 中 分 配 ， 为 了 能 够 在 销毁 内 存 池 时 同时 释放 大 块 内 存 ， 


// 就 把 每 一 次 分 配 的 大 块 内 存 通过 


ngx_pool_large_t 组 成 单 链表 挂 在 


large 成 员 上 


ngx_pool_ large_t *]arge; 


// 所 有 待 清理 资源 (例如 需要 关闭 或 者 删除 的 文件 ， 以 


ngx_pool_cleanup_t 对 象 构成 单 链 表 ， 


// 挂 在 


cleanup 成 员 上 


ngx_pool cleanup_t *cleanup; 


// 内 存 池 执行 中 输出 日 志 的 对 象 


ngx_log_t *]og; 


从 上 面 代码 的 注释 中 可 知 ， 当 申请 的 内 存 算是 大 块 内 存 时 (大 于 
ngx_pool_t 的 max 成 员 ) ， 是 直接 调用 ngx_alloc 从 进程 的 堆 中 分 配 的 ， 
同时 会 再 分 配 一 个 ngx_pool_large_t 结 构 体 挂 在 large 链 表 中 ， 其 定义 如 
下 : 


typedef struct ngx_pool large s ngx_pool large_t,; 
struct ngx_pool large sf{ 
// 所 有 大 块 内 存 通 过 


next 指 针 联 在 一 起 


ngx_pool large _t *next,; 
// alloc 指 向 


ngx_alloc 分 配 出 的 大 块 内 存 。 调 用 


ngx_pfree 后 
alloc 可 能 是 


NULL 
void *alloc; 
}; 


对 于 非常 大 的 内 存 ， 如 果 它 的 生命 周期 远 远 的 短 于 所 属 的 内 存 
池 ， 那 么 在 内 存 池 销 毁 前 提前 的 释放 它 就 变 得 有 意义 了 。 而 ngx_pfree 
方法 就 是 提前 释放 大 块 内 存 的 ， 需 要 注意 ， 它 的 实现 是 遍历 large 链 
表 ， 找 到 alloc 等 于 待 释放 地 址 的 ngx_pool_large_t 后 ， 调 用 ngx_free 释 放 
大 块 内 存 ， 但 不 释放 ngx_pool_large_t 结 构 体 ， 而 是 把 alloc 置 为 NULL 。 
如 此 实现 的 意义 在 于 : 下 次 分 配 大 块 内 存 时 ， 会 期 望 复 用 这 个 
ngx_pool_large_t 结 构 体 。 从 这 里 可 以 想见 ， 如 果 large 链 表 中 的 元 素 很 
多 ， 那 么 ngx_free 的 遍历 损耗 的 性 能 是 不 小 的 ， 如 果 不 能 确定 内 存 确实 
非常 大 ， 最 好 不 要 调用 ngx_pfree。 


再 来 看 看 小 块 内 存 ， 通 过 从 进程 的 堆 中 预 分 配 更 多 的 内 存 
gx_create_pool 的 size 参 数 决 定 预 分 配 大 小 ) ， 而 后 直接 使 用 这 块 内 
存 的 一 部 分 作为 小 块 内 存 返回 给 申请 者 ， 以 此 实现 减少 碎片 和 调用 


malloc 的 次 数 。 它 们 是 放 在 成 员 d 中 维护 管理 的 ， 看 看 ngx_pool_data_t 
征 如 何 定义 的 : 


typedef struct { 
// 指向 未 分 配 的 空闲 内 存 的 首 地 址 


u_char *last; 


// 指向 当前 小 块 内 存 池 的 尾 前 


u_cha *end; 


// 同属 于 一 个 


po01 的 多 个 小 块 内 存 池 间 ， 通 过 


next 相 连 


ngx_pool 七 *next， 
// 每 当 剩 余 空间 不 足以 分 配 出 小 块 内 存 时 ， 


E 


failed 成 员 就 会 加 
failed 成 员 大 于 
4 后 


// \ 
Nginx1.4.4 版 本 ) ， 
ngx_pool_t 的 
current 将 移 向 下 一 个 小 块 内 存 池 


ngx_uint_t failed; 
} ngx_pool data t; 


当 内 存 池 预 分 配 的 size 不 足 使 用 时 ， 束 会 再 接着 分 配 一 个 小 块 内 存 
池 ， 预 分 配 大 小 与 原 内 存 池 相等 ， 且 仍然 使 用 ngx_pool t 表 示 这 个 纯粹 
的 小 块 内 存 池 ， 用 ngx_pool_data_t 的 next 成 员 相 连 。 这 样 ， 这 个 新 增 的 


ngx_pool_t 结 构 体 中 与 小 块 内 存 无 关 的 其 他 成 员 此 时 是 无 意义 的 ， 例 如 
max 不 会 赋值 、large 链 表 为 空 等 。 


ngx_pool t 不 只 硕 望 程序 员 不 用 释放 内 存 ， 而 且 还 能 不 需要 释放 如 
文件 等 资源 。 例 如 第 12 章 介绍 的 upstream 实 现 的 反 向 代理 ， 其 存放 http 
协议 包 体 的 文件 就 希望 它 可 以 随 着 ngx_pool_t 内 存 池 的 销毁 被 自动 天 闭 
并 删除 掉 。 怎 么 实现 呢 ? 表 8-5 中 的 ngx_pool_cleanup_add 方 法 就 用 来 提 
供 这 一 功能 ， 它 会 返回 ngx_pool_cleanup_t 结 构 体 ， 其 定义 如 下 所 示 : 


// 实现 这 个 回调 方法 时 ， 


data 参 数 将 是 

ngx_pool_cleanup_pt 的 

data 成 员 

typedef void (*ngx_pool cleanup_pt)(void *data); 
typedef struct ngx_pool cleanup_s ngx_pool cleanup_t,; 


struct ngx_pool cleanup_s { 
// handler 初 始 为 


NULL， 需 要 设置 为 清理 方法 


ngx_pool cleanup_pt handler; 
// ngx_pool_cleanup_add 方 法 的 


size>0H 时 
data 不 为 
NULL， 此 时 可 改写 


data 指 向 的 内 存 ， 


// 用 于 为 


handler 指 向 的 方法 传递 必要 的 参数 


void *data; 
// 由 


ngx_pool_cleanup_add 方 法 设 


next 成 员 ， 用 于 将 当前 


ngx_pool cleanup_t 
// 添加 到 


ngx_pool_ 的 


cleanup 链 表 中 


ngx_pool cleanup_t *next,; 
/ 


3.8.2 市 就 是 一 个 很 好 的 资源 释放 例子 ， 当 我 们 将 handler 设 为 表 8-5 
中 的 ngx_pool_delete_file 方 法 时 可 以 删除 文件 。 


图 8-9 完 整地 展示 了 ngx_pool t 内 存 池 中 小 块 内 存 、 大 块 内 存 、 资 
源 清 理 链表 间 的 关系 。 图 中 ， 内 存 池 预 分 配 的 小 块 内 存 区 域 剩余 空 闲 
空间 不 足以 分 配 某 些 内 存 ， 导 致 又 分 配 出 2 个 小 块 内 存 池 。 其 中 原 内 存 
池 的 failed 成 员 已 经 大 于 4， 所 以 current 指 向 了 第 2 个 小 块 内 存 池 ， 这 样 
再 次 分 配 小 块 内 存 时 将 会 忽略 第 1 个 小 块 内 存 池 。 (从 这 里 可 以 看 到 ， 
分 配 内 存 的 行为 可 能 导致 每 个 内 存 池 最 大 
NGX_MAX_ALLOC_FROM_POOL-1 字 闻 的 内 存 浪费 。) 图 中 共 分 配 3 
个 大 块 内 存 ， 其 中 第 2 个 大 块 内 存 调用 过 ngx_pfree 方 法 释放 了 。 图 中 还 
挂 载 了 两 个 资源 清理 方法 。 


图 8-10 以 分 配 地 址 对 齐 的 内 存 为 例 ， 列 出 了 主要 步 又 的 流程 图 ， 可 
以 给 读者 朋友 们 更 直观 的 印象 ， 下 面 详细 解释 各 步骤 : 


1) 将 申请 的 内 存 大 小 size 与 ngx_pool t 的 max 成 员 比 较 ， 以 决定 申 
请 的 是 小 块 内 存 还 是 大 块 内 存 。 如 果 size<=max， 则 继续 执行 第 2 步 开 
始 分 配 小 块 内 存 ; 否则 ， 跳 到 第 10 步 分 配 大 块 内 存 。 


2) 取 到 ngx_pool_t 的 current 指 针 ， 它 表示 应 当 首 先 党 试 从 这 个 小 
块 内 存 池 里 分 配 ， 因 为 current 之 前 的 pool 已 经 屡次 分 配 失败 (大 于 4 
次 ) ， 其 剩余 的 空间 多 半 无 法 满足 size。 这 当然 是 一 种 存在 浪费 的 预 
估 ， 但 性 能 不 坏 。 
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图 8-9 ”ngx_pool_t 资 源 池 示 意图 


3) 从 当前 小 块 内 存 池 的 ngx_pool_data_t 的 last 指 针 入 手 ， 先 调用 


ngx_align_ptr 找 到 last 后 最 近 的 对 齐 地 址 。 (可 参考 第 16 章 的 slab 共 享 内 
存 ， 那 里 处 处 需要 地 址 对 齐 。) 


学 


#define ngx_align_ptr(p, a) \ 
(u_char *) (((uintptr_t) (p) + ((uintptr_t) a - 1)) & ~((uintptr_t) a - 1)) 
#define NGX_ALIGNMENT sizeof(unsigned long) 
ngx_pool t *p =... 
// 取得 
last 的 


NGX_ALIGNMENT 字 节 对 齐 地 址 


u_char* m = ngx_align_ptr(p->d.last, NGX_ALIGNMENT); 


4) 比较 对 齐 地 址 与 hgx_pool_data_t 的 end 指 针 间 是 否 可 以 容纳 size 


万 。 如 采 end-m>=size， 那 么 继续 执行 第 5 步 准 备 返 回 地 址 m;， 人 否则， 


再 检查 ngx_pool_data_t 的 next 指 针 是 否 为 NULL， 如 果 是 空 指针 ， 那 么 


跳 到 第 6 步 准 备 再 申请 新 的 小 块 内 存 池 ， 不 为 空 则 跳 到 第 3 步 继续 遍历 
小 块 内 存 池 构成 的 链表 。 


5) 先 将 ngx_pool_data_t 的 last 指 针 置 为 下 次 空 内 内 存 的 首 地 址 ， 例 


如 : 


p->d.last = m + size,; 


再 返回 地 址 m， 分 配 内 存 流程 结 


6) 分 配 一 个 大 小 与 上 一 个 ngx_pool_t 一 致 的 内 存 池 专用 于 小 块 内 
存 的 分 配 。 内 存 池 大 小 获取 很 商 单 ， 如 下 : 


(size_t) ( pool->d.end - (u_char *) pool) 


7) 将 新 内 存 池 的 空闲 地 址 的 首 地 址 对 齐 ， 作 为 返回 给 申请 的 内 
存 ， 再 设 last 到 空 采 内 存 的 首 地 址 。 


8) 从 current 指 向 的 小 块 内 存 池 开始 遍历 到 当前 的 新 内 存 池 ， 依 次 
将 各 failed 成 员 加 1， 并 把 current 指 回首 个 failed<=4 的 小 块 内 存 池 ， 用 于 
下 一 次 的 小 块 内 存 分 配 。 


9) 返回 第 7 步 对 齐 的 地 址 ， 分 配 流程 结束 。 


10) 调用 ngx_alloc 方 法 从 进程 的 堆 内 存 中 分 配 size 大 小 的 内 存 。 


11) 仿 历 ngx_pool_t 的 large 链 表 ， 看 看 有 没有 ngx_pool_large_t 的 
alloc 成 员 值 为 NULL (这 个 alloc 指 向 的 大 块 内 存 执行 过 ngx_pfree 方 
法 ) 。 如 果 找 到 了 这 个 ngx_pool large t， 继 续 执 行 第 12 步 ， 否 则 ， 跳 
到 第 13 步 执行 。 需 要 注意 的 是 ， 为 了 防止 large 链 表 过 大 ， 允 历次 数 是 
有 限制 的 ， 例 如 最 多 4 次 还 未 找到 alloc==NULL 的 元 素 ， 也 会 跳出 这 个 
过 有 历 循环 执行 第 13 步 。 


12) 把 ngx_pool_large _t 的 alloc 成 员 置 为 第 10 步 分 配 的 内 存 地 址 ， 
返回 地 址 ， 分 配 流程 结束 。 


13) 从 内 存 池 中 分 配 出 ngx_pool_large_t 结 构 体 ，alloc 成 员 置 为 第 
10 步 分 配 的 内 存 地 址 ， 将 ngx_pool_large_t 添 加 到 ngx_pool_t 的 large 链 表 
首部 ， 返 回 地 址 ， 分 配 流程 结束 。 


1 ) 将 分 配 大 小 size 与 ngx_pool_t 的 max 成 员 比 较 


[size<=max] 


(2) 从 current 成 员 指 问 的 ngx_pool_t 开 始 遍 历 pool 链 表 ) 


[size>max] 


3 ) 从 当前 ngx_pool_data_t 的 last 指 针 找 到 对 齐 地 址 


4 ) 比较 新 地 址 与 end 之 前 的 空间 大 小 是 否 可 容纳 size 


[遍历 ] [找到 一 个 pool 可 以 分 出 size 地 址 ] 


[链表 中 的 所 有 pool 都 无 法 分 出 size 内 存 ] 


5 ) 设 last 为 对 齐 地 址 加 上 size， 返 回 对 齐 地 址 


6 ) 分 配 新 的 ngx_pool_t， 大 小 与 第 1 个 pool 一 致 


重 置 last 指 针 


7 ) 对 齐 空闲 内 存 首 地 址 ， 


10 ) 分 配 一 块 size 大 小 的 内 存 


2) 检查 各 pool 的 failed 次 数 ， 重 置 current 指 针 


(un ) 遍历 pool 的 large 链 表 ， 找 出 alloce=NULL 的 指针 ) 


9 ) 返回 新 pool 分 配 出 的 对 齐 内 存 地 址 > i 
[未 找到 或 遍历 
个 数 达 到 上 限 ] 


[找到 alloc 值 为 NULL 的 成 员 ] 


12 ) 将 刚 分 配 内 存 赋 给 alloc， 并 返回 地 址 


13 ) 新 分 配 ngx_poolL_large_t 结 构 赋 值 后 挂 在 large 链 表 上 ， 返 回 地 址 


图 8-10 “分 配 地 址 对 齐 内 存 的 流程 图 


8.8 ”小 结 


本 章 主要 理 清 了 Nginx 的 设计 思路 ， 知 道 它 是 如 何 达 到 高 性 能 、 高 
可 靠 性 、 高 可 伸缩 性 、 高 可 修改 性 等 要 求 的 。 在 此 基础 上 上， 我们 以 
ngx_cycle_t 数 据 结 构 为 核心 ， 介 绍 了 Nginx 框 架 如 何 局 动 、 初 始 化 、 加 
载 各 Nginx 模 块 的 代码 ， 以 及 master 进 程 、worker 进 程 如 何在 工作 循环 
中 运行 。 对 于 worker 进 程 来 说 ， 它 的 工作 流程 更 多 地 体现 在 具体 的 模 
块 上 。 例 如 ， 对 于 HTTP 请 求 来 说 ，worker 进 程 大 都 是 由 HTTP 模 块 所 
占用 的 ， 特 别 是 8.5 节 中 提 到 的 ngx_process_events_and_timers 方 法 ， 这 
是 第 9 章 中 事件 模块 将 和 要 讲述 的 内 容 ， 因 此 ， 对 于 worker 进 程 的 工作 循 
环 ， 本 章 并 没有 做 详细 的 说 明 。 对 于 master 进 程 ，8.6 世 内 容 基本 上 涉 
及 了 它 在 工作 循环 中 执行 的 所 有 流程 。 而 对 于 cache manage 和 cache 
loader 进 程 ， 它 们 是 与 文件 缓存 模块 密切 相关 的 ， 在 不 使 用 文件 缓存 
时 ， 这 两 个 进程 也 不 会 启动， 它们 与 框架 代码 没有 多 少 天 联 ， 本 革 只 
是 进行 了 简单 说 明 。 


ngx_pool t 内 存 池 是 一 个 很 基础 的 设计 ， 本 章 通 过 分 析 其 实现 可 
以 帮助 读者 朋友 们 正确 地 使 用 ngx_pool_t 内 存 池 ， 方 便 阅 读 后 续 章 


+ 


HH O 


通过 阅读 本 章 的 内 容 ， 读 者 应 该 对 Nginx 的 设计 结构 有 了 大 致 的 了 
解 ， 这 样 在 修改 Nginx 的 源码 或 者 开发 一 些 异 常 强 大 且 深 入 的 Nginx 模 
块 时 束 可 以 得 心 应 手 了 ， 因 为 只 有 在 不 违反 Nginx 本 号 设计 原则 的 前 提 
下 才 会 保留 8.2 节 中 所 述 的 优点 。 同 时 ， 本 章 内 容 是 后 续 章 万 的 基础 ， 
在 了 解 事件 模块 、HTTP 模 块 、mail 模 块 前 ， 必 须 对 Nginx 整 个 的 模块 
分 布 、 事 件 驱 动 、 请 求 的 多 阶段 划分 等 特点 有 清晰 的 认识 ， 这 样 在 阅 
读 后 续 章 市 时 可 以 做 到 事半功倍 。 


第 9 草 ”事件 模块 


在 上 文中 提 到 ，Nginx 是 一 个 事件 驱动 架构 的 Web 服 务 器 ， 本 章 将 
全 面 探 讨 Nginx 的 事件 驱动 机 制 是 如 何 工 作 的 。ngx_event_t 事 件 和 
ngx_connection_t 连 接 是 处 理 TCP 连 接 的 基础 数据 结构 ， 在 对 它们 有 了 
基本 了 解 后 ， 在 9.4 节 将 首先 探讨 核心 模块 ngx_events_module， 它 定义 
了 一 种 新 的 模块 类 型 一 事件 模块 ， 而 在 9.5 节 将 开始 说 明 第 1 个 事件 模 
块 ngx_event_core_ module， 它 的 职责 更 多 地 体现 在 如 何 管理 当前 正在 
使 用 的 事件 驱动 模式 。 例 如 ， 在 Nginx 启 动 时 决定 到 底 是 基于 select 还 
是 epoll 来 监控 网 络 事件 。 


epoll 是 目前 Linux 操 作 系统 上 最 强大 的 事件 管理 机 制 ， 本 书 搞 述 的 
场景 都 是 使 用 epoll 来 驱动 事件 的 处 理 ， 在 9.6 入 中， 首先 会 深入 到 
Linux 内 核 ， 研 究 epoll 的 实现 原理 和 使 用 方法 ， 以 此 明确 epoll 的 高 并 发 
征 怎 么 来 的 ， 以 及 怎样 使 用 epoll 才 能 发 挥 它 的 最 大 性 能 。 接 着 ， 殉 到 
了 ngx_epoll_module 模 块 “ 亮 相 ? 的 时 候 了 ， 这 里 可 以 看 到 一 个 实际 的 事 
件 驱 动 模块 是 如 何 实现 声明 过 的 事件 抽象 接口 的 见 9.1 节 ) ， 同 时 这 
个 模块 也 是 高 效 使 用 epoll 的 较 好 的 例 于 。 例 如 ， 在 使 用 epol 时 ， 非 党 
容易 遇 到 过 期 事件 的 处 理 问 题 ，Nginx 束 使 用 了 一 个 巧妙 的 、 成 本 低廉 
的 方法 完美 地 解决 了 这 个 问题 ， 稍 后 读者 将 会 看 到 这 个 小 技巧 。 


Nginx 的 定时 右 事 件 是 由 第 7 草 中 谈 到 的 红 黑 树 实现 的 ， 它 也 由 
epoll 等 事件 模块 触发 ， 在 9.7 市 中 ， 读 者 将 看 到 Nginx 如 何 实 现 独 立 的 
定时 需 功 能 。 


在 9.8 节 中 ， 我 们 开始 综合 性 地 介绍 事件 处 理 框 架 ， 这 里 将 会 使 用 
到 9.1 节 ~9.7 节 中 的 所 有 知识 。 这 一 节 将 说 明 核 心 的 
ngx_process_events_and_timers 方 法 处 理 网 络 事 件 、 定 时 器 事件 、post 
事件 的 完整 流程 ， 同 时 读者 会 看 到 Nginx 是 如 何 解 决 多 个 worker 子 进程 
监听 同一 端口 引起 的 “ 惊 群 " 现 象 的 ， 以 及 如 何 均衡 多 个 worker 子 进程 
上 处 理 的 连接 数 。 


训 无 疑问 ，Linux 内 核 提 供 的 文件 异步 JO 是 不 同 于 glibc 库 实现 的 
多 线程 伪 异 步 JO 的 ， 它 充分 利用 了 在 Linux 内 核 中 CPU 与 IO 设备 独立 
工作 的 特性 ， 使 得 进程 在 提交 文件 异步 WO 操作 后 可 以 占用 CPU 做 其 他 
工作 。 在 9.9 中 ， 将 会 讨论 这 种 高 效 读 取 磁 盘 的 机 制 ， 在 简单 说 明 它 
的 使 用 方式 后 ， 读 者 还 可 以 看 到 文件 异步 JO 是 如 何 集成 到 
ngx_epoll_module 模 块 中 与 epoll 一 起 工作 的 。 


9.1 事件 处 理 框 染 概 述 


事件 处 理 框 架 所 要 解决 的 问题 古 如 何 收集 、 管 理 、 分 发 事件 。 这 
里 所 说 的 事件 ， 主 要 以 网 络 事件 和 定时 器 事件 为 主 ， 而 网 络 事件 中 文 
以 TCP 网 络 事 件 为 主 《Nginx 毕 竟 是 个 web 服务 右 ) ， 本 章 所 述 的 事件 
处 理 框 染 都 将 围绕 这 两 种 事件 进行 。 


定时 颖 事件 将 在 9.7 市 中 阐述 ， 因 为 它 的 实现 简单 而 且 独 立 ， 同 时 
它 基 于 网 络 事件 的 触发 实现 ， 并 不 涉及 操作 系统 内 核 。 这 里 移 来 了 解 
一 下 Nginx 是 如 何 收集 、 管 理 TCP 网 络 事件 的 。 由 于 网 络 事件 与 网 卡 中 
断 处 理 程序 、 内 核 提 供 的 系统 调用 密切 相关 ， 所 以 网 络 事件 的 驱动 既 
取决 于 不 同 的 操作 系统 平台 ， 在 同一 个 操作 系统 中 也 受制 于 不 同 的 操 
作 系 统 内 核 版 本 。 这 样 的 话 ，Nginx 支 持 多 少 种 操作 系统 (包括 支持 哪 
些 版 本 ) ， 就 必须 提供 多 少 个 事件 驱动 机 制 ， 因 为 基本 上 每 个 操作 系 
统 提供 的 事件 驱动 机 制 (通常 事件 驱动 机 制 还 有 个 名 字 ， 叫 做 VO 多 路 
复 用 ) 都 是 不 同 的 。 例 如 ，Linux 内 核 2.6 之 前 的 版 本 或 者 大 部 分 类 
UNIX 操 作 系 统 都 可 以 使 用 poll (ngx_poll_ module 模 块 实现 ) 或 者 select 
(ngx_select_module 模 块 实现 ) ， 而 Linux 内 核 2.6 之 后 的 版 本 可 以 使 用 
epoll (ngx_epoll_module 模 块 实现 ) ，FreeBSD 上 可 以 使 用 kqueue 


(ngx_kqueue_module 模 块 实现 ) ，Solaris 10 上 可 以 使 用 eventport 
(ngx_eventport_module 模 块 实现 ) 等 。 


如 此 一 来 ， 事 件 处 理 框架 需要 在 不 同 的 操作 系统 内 核 中 选择 一 种 
事件 驱动 机 制 支持 网 络 事件 的 处 理 (Nginx 的 高 可 移植 性 亦 来 源 于 
此 ) 。Nginx 是 如 何 做 到 这 一 点 的 呢 ? 


首先 ， 它 定义 了 一 个 核心 模块 ngx_events_module， 这 样 在 Nginx 
启动 时 会 调用 ngx_init_cycle 方 法 解析 配置 项 ， 一 旦 在 nginx.conf 配 置 文 
件 中 找到 ngx_events_module 感 兴趣 的 “events{}” 配 置 项 ， 
ngx_events_module 模 块 束 开始 工作 了 。 在 图 9-3 中 ，ngx_events_module 
模块 定义 了 事件 类 型 的 模块 ， 它 的 全 部 工作 就 是 为 所 有 的 事件 模块 解 
析 “events{}” 中 的 配置 项 ， 同 时 管理 这 些 事 件 模 块 存储 配置 项 的 结构 
体 。 


其 次 ，Nginx 定 义 了 一 个 非常 重要 的 事件 模块 
ngx_event_core_module， 这 个 模块 会 决定 使 用 哪 种 事件 驱动 机 制 ， 以 
及 如 何 管理 事件 。 在 9.5 方 中， 将 会 评 细 讨论 ngx_event_core_module 模 
块 在 局 动 过 程 中 的 工作 ， 而 在 9.8 节 中 ， 则 会 在 事件 框架 的 正常 运行 中 
再 次 看 到 ngx_event_core_module 模 块 的 “身影 ”。 


最 后 ，Nginx 定 义 了 一 系列 (目前 为 9 个 ) 运行 在 不 同 操作 系统 、 
不 同 内 核 版 本 上 的 事件 驱动 模块 ， 包 括 : ngx_epoll module、 
ngx_kqueue module ~ ngx_poll module ~ ngx_select_module、 
ngx_devpoll module 、 ngx_eventport module ~ ngx_aio module、 


ngx_rtsig_module 和 基于 Windows 的 ngx_select_module 模 块 。 在 


ngx_event_core_module 模 块 的 初始 化 过 程 中 ， 将 会 从 以 上 9 个 模块 中 选 
取 1 个 作为 Nginx 进 程 的 事件 驱动 模块 。 


下 面 开 始 介绍 事件 碟 动 模块 接口 的 相关 知识 。 


事件 模块 是 一 种 新 的 模块 类 型 ， ee 
本 接口 ， 而 针对 于 每 一 种 不 同类 型 的 模块 ， 都 有 一 个 结构 体 来 描述 
一 类 模块 的 通用 接口 ， 这 个 接口 保存 在 ngx_module_t 结 构 体 的 ctx 成 员 
中 。 例 如 ， 核 心 模块 的 通用 接口 是 ngx_core_module _t 结 构 体 ， 而 事件 
模块 的 通用 接口 则 是 ngx_event_module t 结 构 体 (参见 图 8-1) ， 具 体 
如 下 所 示 * 


typedef struct { 
// 事件 模块 的 名 称 


ngx_str_t *name; 
// create_conf 和 


init_conf 方 法 的 调用 可 参见 图 


9-3 


// 在 解析 配置 项 前 ， 这 个 回调 方法 用 于 旬 


| 建 存储 配置 项 参数 的 结构 体 


void *(*create conf)(ngx_cycle t *cycle); 


/* 在 解析 配置 项 完成 后 ， 


init_conf 方 法 会 被 调用 ， 用 以 综合 处 理 当前 事件 模块 感 兴趣 的 全 部 配置 项 


char *(*init -Conf ) (ngx— cycle t *cycle, void *conf); 
// 对 于 事件 驱动 机 制 ， 每 个 事件 模块 需要 实现 的 


10 个 抽象 方法 


ngx_event_actions_t actions 
} ngx_event_module_t,; 


ngx_event_module_t 中 的 actions 成 员 是 定义 事件 驱动 模块 的 核心 方 
法 ， 下 面 重点 看 一 下 actions 中 的 这 10 个 抽象 方法 ， 代 码 如 下 。 


typedef struct { 
/* 添 加 事件 方法 ， 它 将 负责 


1 个 感 兴趣 的 事件 添加 到 操作 系统 提供 的 事件 驱动 机 制 (如 


[号 


epoll、 


kqueue 等 ) 中 ， 这 样 ， 在 事件 发 生 后 ， 将 可 以 在 调用 下 面 的 


process_events 时 获取 这 个 事件 


*/ 
ngx_int_t (*add)(ngx_event t *ev, ngx_int _t event, ngx_uint_t flags); 


/* 删 除 事件 方法 ， 它 将 把 


N 


1 个 已 经 存在 于 事件 驱动 机 制 中 的 事件 移 除 ， 这 样 以 后 即使 这 个 事件 发 生 ， 调 用 


process_events 方 法 时 也 无 法 再 获取 这 个 事件 


ngx_int_t (*del)(ngx_event t *ev，ngx_int_t event, ngx_uint_t flags) 
/局 用 


1 个 事件 ， 目 前 事件 框架 不 会 调用 这 个 方法 ， 大 部 分 事件 驱动 模块 对 于 该 方法 的 实现 都 是 与 上 面 的 
add 方 法 完全 一 致 的 


*/ 
ngx_int_t (*enable)(ngx_ event t *ev, ngx_int_t event, ngx_uint_t flags); 
/* 大 本 本 


1 个 事件 ， 目 前 事件 框架 不 会 调用 这 个 方法 ， 大 部 分 事件 驱动 模块 对 于 该 方法 的 实现 都 是 与 上 面 的 


ngx_int t (*disable)(ngx_ 0 _t *ev, ngx_int_t event, ngx_uint_t flags); 


/* 向 事件 驱动 机 制 中 添加 一 个 新 的 连接 ， 这 意味 着 连接 上 的 读 写 事件 都 添加 到 事件 驱动 机 制 中 了 


*/ 
ngx_int_t (*add_ conn)(ngx_connection t *c); 


// 从 事件 驱动 机 制 中 移 除 一 个 连接 的 读 写 事件 


ngx_int_t (*del_ on Mg connection t *c, ngx_uint_t flags); 


/* 仅 在 多 线程 环境 下 会 被 调 前 ， 
Nginx 在 产品 环境 下 还 不 会 以 多 线程 方式 运行 ， 因 此 这 里 不 做 讨论 


了 


ngx_int_t (*process changes) (ngx_cycle t *cycle, ngx_uint_t nowait); 


/* 在 正常 的 工作 循环 中 ， 将 通过 调用 


process_events 方 法 来 处 理事 件 。 这 个 方法 仅 在 第 
8 章 中 提 到 的 


ngx_process_events_and_timers 方 法 中 调用 ， 它 是 处 理 、 分 发 事件 的 核心 
yh 


ngx_int_t (*process events) (ngx_cycle t *cycle, ngx_msec_t timer, 
ngx_uint_t flags); 


); 
// 初始 化 事件 驱动 模块 的 方法 


ngx_int_t (*init)(ngx_cycle t *cycle, ngx_msec_t timer); 
// 退出 事件 驱动 模块 前 调用 的 方法 


Me ee 
ngx_event_core_module 和 9 个 事件 驱动 模块 都 必须 在 ngx_module_t 
结构 体 的 ctx 成 员 中 实现 ngx_event_module_t 接 口 。 读 者 将 在 9.5 广 中 看 
到 ngx_event_core_module 模 块 是 如 何 实现 该 接口 的 ， 对 于 具体 的 事件 
驱动 模块 ， 这 里 只 讨论 ngx_epoll_module 事 件 驱 动 模块 ， 在 9.6 节 中 ， 
我 们 才 会 介绍 ngx_epoll_module 是 如 何 实 现 该 接口 的 。 


9.2 Nginx 事 件 的 定义 


在 Nginx 中 ， 每 一 个 事件 都 由 ngx_event_t 结 构 体 来 表示 。 本 世 说 明 
ngx_event_t 中 每 一 个 成 员 的 含义 ， 如 下 所 示 。 


typedef struct ngx_event_s ngx_event_t,; 
struct ngx_event_s { 


/* 事 件 相关 的 对 象 。 通 常 
data 都 是 指向 


ngx_connection_t 连 接 对 象 。 开 启 文 件 异 步 


I/0 时 ， 它 可 能 会 指向 
ngx_event_aio_t 结 构 体 
< 


void *data,; 


/* 标 志 位 ， 为 


1 时 表示 事件 是 可 写 的 。 通 常情 况 下 ， 它 表示 对 应 的 
TCP 连 接 目 前 状态 是 可 写 的 ， 也 就 是 连接 处 于 可 以 发 送 网 络 包 的 状态 


unsigned write:1,; 
/* 标 志 位 ， 为 


1 时 表示 为 此 事件 可 以 建立 新 的 连接 。 通 常情 况 下 ， 在 


ngx_cycle_t 中 的 
1istening 动 态 数组 中 ， 每 一 个 监听 对 象 


ngx_listening_t 对 应 的 读 事件 中 的 


accept 标 志 位 才 会 是 


1*y 
unsigned accept:1; 
/* 这 个 标志 位 用 于 区 分 当前 事件 是 否 是 过 期 的 ， 它 仪 仅 是 给 事件 驱动 模块 使 用 的 ， 而 事件 消费 模块 可 不 用 
关心 。 为 什么 需要 这 个 标志 位 呢 ? 当 开始 处 理 一 批 事件 时 ， 处 理 前 面 的 事件 可 能 会 关闭 一 些 连接 ， 而 这 些 连 接 
可 能 影响 这 批 事件 中 还 未 处 理 到 的 后 面 的 事件 。 这 时 ， 可 通过 


instance 标 志 位 来 避免 处 理 后 面 的 已 经 过 期 的 事件 。 在 


9.6 广 中 ， 将 详细 描述 


证 


ngx_epoll_module 是 如 何 使 用 


instance 标 志 位 区 分 过 期 事件 的 ， 这 是 一 个 巧妙 的 设计 方法 


“7 
unsigned instance:1; 
/* 标 志 位 ， 为 

1 时 表示 当前 事件 是 活跃 的 ， 为 


人 。 这 个 状态 对 应 着 事件 驱动 模块 处 理 方式 的 不 同 。 例 如 ， 在 添加 事件 、 删 除 事件 和 处 理 
了 件 时 ， 


active 标 志 位 的 不 同 都 会 对 应 着 不 同 的 处 理 方式 。 在 使 用 事件 时 ， 一 般 不 会 直接 改变 


2 


山中 


active 标 志 位 


*/ 
unsigned active:1; 
/* 标 志 位 ， 为 


1 时 表示 禁用 事件 ， 仅 在 


kqueue 或 者 
rtsig 事 件 驱 动 模块 中 有 效 ， 而 对 于 
驱动 模块 则 无 意义 ， 这 里 不 再 详 i 


让 


epoll 事 伯 


[Es 


Sp 
unsigned disabled:1; 
/* 标 志 位 ， 为 
1 时 表示 当前 事件 已 经 准备 就 绪 ， 也 就 是 说 ， 人 允许 这 个 事件 的 消费 模块 处 理 这 个 事件 。 在 


HTTP 框 架 中 ， 经 常会 检查 事件 的 


ready 标 志 位 以 确定 是 否 可 以 接收 请 求 或 者 发 送 响应 


2 
unsigned ready:1; 
/* 该 标志 位 仅 对 
kqueue, 


eventport 等 模块 有 意义 ， 而 对 于 


Linux 上 的 


epoll 事 件 驱 动 模块 则 是 无 意义 的 ， 限 于 篇 幅 ， 不 再 详细 说 明 
*/ 

unsigned oneshot :1， 

// 该 标志 位 用 于 异步 


AIO 事 件 的 处 理 ， 在 


9.9 节 中 会 详细 描述 


unsigned complete:1; 
// 标志 位 ,为 


1 时 表示 当前 处 理 的 字符 流 已 经 结束 


unsigned eof :1 
// 标志 位 ， 为 


1 时 表示 


山中 


件 在 处 


过 程 中 出 现 错误 


unsigned error:1; 
/* 标 志 位 ， 为 


1 时 表示 这 个 


dd 


timer_set 都 用 于 


9.7 节 将 要 介绍 的 定时 器 


“水 


unsigned timedout:1; 
// 标志 位 ， 为 


1 时 表示 这 个 事件 存在 于 定时 器 中 


Ll 


unsigned timer_set:1,; 


// 标志 位 ， 


delayed 为 


1 时 表示 需要 延迟 处 理 这 个 事 人 


了 件 已 经 超时 ， 用 以 提示 事件 的 消费 模块 做 超时 处 理 ， 


它 仅 


I 


unsigned delayed:1,; 


// 该 标志 位 


目前 没有 使 用 


unsigned read discarded:1; 


于 限 速 功 角 


// 标志 位 ， 


目前 这 个 标志 位 未 被 使 


unsigned unexpected eof:1; 
/* 标 志 位 ， 为 


TCP 连 接 ， 也 就 是 说 ， 经 过 


CSC 


TCP 三 次 握手 后 并 不 建立 连接 ， 而 是 要 等 到 真 ] 


TCP 连 接 


“A 


unsigned deferred accept:1,; 


/* 标 志 位 ， 为 


1 时 表示 等 待 字 符 流 结束 ， 它 只 与 


kqueue 和 


FE 收 到 数据 包 后 才 会 建 


EE 
) 


aio 事 件 驱 动机 制 有 关 ， 不 再 详 i 


全 


*/ 

unsigned pending eof:1; 
#if !(NGX_THREADS) 

// 标志 位 ， 如 果 为 


表示 在 处 理 


post 事 件 时 ， 当 前 事件 已 经 准备 就 绪 


P= 


1， 见 


unsigned posted_ready:1; 
#endif 
/* 标 志 位 ， 在 


epo11 事 件 驱 动机 制 下 表示 一 次 尽 可 能 多 地 建立 


TCP 连 接 ， 它 与 


multi_accept 配 置 项 对 应 ， 实 现 原理 参见 


二 


9.8.17 


unsigned available:1,; 
// 这 个 事件 发 生 时 的 处 理 方法 ， 每 个 事件 消费 模块 都 会 重新 实现 它 


ngx_event_handler_pt handler; 
#if (NGX_HAVE_AIO) 
#if (NGX_HAVE_IOCP) 
// Windows 系 统 下 的 一 种 事件 驱动 模型 ， 这 里 不 再 详 壕 


ngx_event_ovilp_t ovilp; 
#else 
// Linux aio 机 制 中 定义 的 结构 体 ， 在 


9.9 节 中 会 详细 说 明 它 


Struct aiocb aiocb 
#endif 
#endif 

// 由 了 


nn 


epoll 事 件 驱 动 方式 不 使 


index， 所 以 这 里 不 再 说 


CO 


ngx_uint_t index; 


// 可 用 于 记录 


error_1og 日 志 的 


ngx_1og_t 对 象 


ngx_log_t *1og ， 


// 定时 器 节点 ， 用 于 定时 器 红 黑 树 中 ， 在 


9.7 节 会 详细 介绍 


ngx_rbtree_node _t timer; 
// 标志 位 ， 为 


1 时 表示 当前 事件 已 经 关闭 ， 


epol1 模 块 没有 使 用 它 


unsigned closed:1; 
// 该 标志 位 目前 无 实际 意义 


unsigned channel:1; 
// 该 标志 位 目前 无 实际 意义 


unsigned resolver:1; 


/*post 事 件 将 会 构成 一 个 队列 再 统一 处 理 ， 这 个 队列 以 


么 说 


next 和 


prev 作 为 链表 指针 ， 以 此 构成 一 个 简易 的 双向 链表 ， 其 中 


next 指 向 后 一 个 事件 的 地 址 ， 


prev 指 向 前 一 个 事件 的 地 址 


*/ 
ngx_event_t *next; 
ngx_event_t **prev; 


}; 


每 一 个 事件 最 核心 的 部 分 是 handler 回 调 方法 ， 它 将 由 每 一 个 事件 
消费 模块 实现 ， 以 此 决定 这 个 事件 究竟 如 何 “ 消 费 *。 下 面 来 看 一 下 
handler 方 法 的 原型 ， 代 码 如 下 。 


typedef void (*ngx_event_handler_pt)(ngx_event_t *ev); 


所 有 的 Nginx 模 块 只 要 处 理事 件 束 必然 要 设置 handler 回 调 方法 ， 后 
续 章 广 会 有 许多 handler 回 调 方法 的 例子 ， 这 里 不 再 详 述 。 


下 面 开始 说 明 操 作 事件 的 方法 。 


事件 是 不 需要 创建 的 ， 因 为 Nginx 在 启动 时 已 经 在 ngx_cycle_t 的 
read_events 成 员 中 预 分 配 了 所 有 的 读 事 件 ， 并 在 write_events 成 员 中 预 
分 配 了 所 有 的 写 事件 。 事 实 上 ， 从 图 9-1 中 我 们 会 看 到 每 一 个 连接 将 自 
动 地 对 应 一 个 写 事件 和 读 事件 ， 只 要 从 连接 池 中 获取 一 个 空 采 连接 就 
可 以 拿 到 事件 了 。 那 么 ， 怎 么 把 事件 添加 到 epoll 等 事件 驱动 模块 中 
呢 ? 需要 调用 9.1.1 节 中 提 到 的 ngx_event_actions_t 结 构 体 的 add 方 法 或 
者 del 方 法 吗 ? 答案 是 Nginx 为 我 们 封装 了 两 个 简单 的 方法 用 于 在 事件 
驱动 模块 中 添加 或 者 移 除 事件 ， 当 然 ， 也 可 以 调用 ngx_event_actions { 
结构 体 的 add 或 者 del 等 方法 ， 但 并 不 推荐 这 样 做 ， 因 为 Nginx 提 供 的 
ngx_handle_read_event 和 和 ngx_handle_write_event 方 法 还 是 做 了 许多 通用 
性 的 工作 的 。 


先 看 一 下 ngx_handle_read_event 方 法 的 原型 : 


ngx_int_t ngx_handle_read event(ngx_event_t *rev, ngx_uint_t flags); 


ngx_handle_read_event 方 法 会 将 读 事 件 添加 a 到 事件 驱动 模块 中 ， 
这 样 该 事件 对 应 的 TCP 连 接 上 一 旦 出 现 可 读 事 件 (如 接收 到 TCP 连 接 
另 一 端 发 送 来 的 字符 流 ) 就 会 回调 该 事件 的 handler 方 法 。 


下 面 看 一 下 ngx_handle_read_event 的 参数 和 返回 值 。 参 数 rev 是 要 
操作 的 事件 ，flags 将 会 指定 事件 的 驱动 方式 。 对 于 不 同 的 事件 驱动 模 
块 ，flags 的 取 值 范围 并 不 同 ， 本 书 以 Linux 下 的 epol 为 例 ， 对 于 
ngx_epoll_ module 来 说 ，flags 的 取 值 范围 可 以 是 0 或 者 
NGX_CLOSE_ EVENT (NGX_CLOSE_EVENT 仅 在 epoll 的 LT 水 平 触发 
模式 下 有 效 ) ，Nginx 主 要 工作 在 ET 模式 下 ， 一 般 可 以 忽略 flags 这 个 
人 参数。 该 方法 返回 NGX_OK 表 示 成 功 ， 返 回 NGX_ERROR 表 示 失 败 。 


再 看 一 下 ngx_handle_write_event 方 法 的 原型 : 


ngx_int_t ngx_handle write event(ngx_event_t *wev, size_t lowat); 


ngx_handle_write_event 方 法 会 将 写 事件 添加 到 事件 驱动 模块 中 。 
wev 是 要 操作 的 事件 ， 而 lowat 则 表示 只 有 当 连 接 对 应 的 套 接 字 缓冲 区 
中 必须 有 lowat 大 小 的 可 用 空间 时 ， 事 件 收集 器 (如 select 或 者 
epoll_wait 调 用 ) 才能 处 理 这 个 可 写 事 件 〈lowat 参 数 为 0 时 表示 不 考虑 
可 写 缓 神 区 的 大 小 ) 。 该 方法 返回 NGX_OK 表 示 成 功 ， 返 回 
NGX_ERROR 表 示 失 败 。 


一 般 在 向 epoll 中 添加 可 读 或 者 可 写 事件 时 ， 都 是 使 用 
ngx_handle_read_event 或 者 ngx_handle_write_event 方 法 的 。 对 于 事件 驱 
动 模块 实现 的 ngx_event_actions 结 构 体 中 的 事件 设置 方法 ， 最 好 不 要 直 
接 调用 ， 下 面 这 4 个 方法 直接 使 用 时 都 会 与 具体 的 事件 驱动 机 制 强 相 


关 ， 而 使 用 ngx_handle _read_event 或 者 ngx_handle_ write _event 方 法 则 可 
以 屏蔽 这 种 差异 。 


#define ngx_add_event ngx_event_actions.add 
#define ngx_del event ngx_event_actions.del 
#define ngx_add_conn ngx_event_actions.add_conn 


#define ngx_del_ conn ngx_event_actions.del conn 


9.3 Nginx 连 接 的 定义 


作为 web 服务 器 ， 每 一 个 用 户 请 求 至 少 对 应 着 一 个 TCP 连 接 ， 为 了 
及 时 处 理 这 个 连接 ， 至 少 需要 一 个 读 事件 和 一 个 写 事件 ， 使 得 epoll 可 
以 有 效 地 根据 触发 的 事件 调度 相应 模块 读 取 请 求 或 者 发 送 响应 。 
此 ，Nginx 中 定义 了 基本 的 数据 结构 ngx_connection_t 来 表示 连接 ， 这 个 
连接 表示 是 客户 端 主动 发 起 的 、Nginx 服 务 器 被 动 接受 的 TCP 连 接 ， 我 
们 可 以 简单 称 其 为 被 动 连接 。 同 时 ， 在 有 些 请 求 的 处 理 过 程 中 ，Nginx 
会 试图 主动 向 其 他 上 游 服 务 器 建立 连接 ， 并 以 此 连接 与 上 游 服 务 器 通 
信 ， 因 此 ， 这 样 的 连接 与 ngx_connection_t 又 是 不 同 的 ，Nginx 定 义 了 
ngx_peer_connection_t 结 构 体 来 表示 主动 连接 ， 当 然 ， 
ngx_peer_connection_t 主 动 连 接 是 以 ngx_connection_t 结 构 体 为 基础 实现 
的 。 本 闻 将 说 明 这 两 种 连接 中 各 字段 的 意义 ， 同 时 需要 注意 的 是 ， 这 
两 种 连接 都 不 可 以 随意 创建 ， 必 须 从 连接 池 中 获取 ， 在 9.3.3 广 中 会 说 
明 连 接 池 的 用 法 。 


9.3.1 被动 连接 


本 章 中 未 加 修饰 提 到 的 “连接 ”部 是 指 客户 端 发 起 的 、 服 务 器 被 动 
接受 的 连接 ， 这 样 的 连接 都 是 使 用 ngx_connection_t 结 构 体 表示 的 ， 其 
是 人 下 


typedef struct ngx_connection s ngx_connection t; 
struct ngx_connection s { 
/* 连 接 未 使 用 时 ， 


data 成 员 用 于 充当 连接 池 中 空间 连接 链表 中 的 
next 指 针 。 当 连接 被 使 用 时 ， 

data 的 意义 由 使 用 它 的 

Nginx 模 块 而 定 ， 如 在 


HTTP 框 架 中 ， 


data 指 向 
ngx_http_request_t 请 求 
*/ 


void *data; 
// 连接 对 应 的 读 事 人 


全 


ngx_event_t *read; 


// 连接 对 应 的 写 事件 


ngx_event_t *write; 


// 套 接 字句 柄 


ngx_socket_t fd; 
// 直接 接收 网 络 字符 流 的 方法 


ngx_recv_pt recv; 


// 直接 发 送 网 络 字符 流 的 方法 


ngx_send_pt send; 
// 以 


ngx_chain_t 链 表 为 参数 来 接收 网 络 字 符 流 的 方法 
ngx_recv_chain pt recv_chain; 

// 以 
ngx_chain_t 链 表 为 参数 来 发 送 网 络 字符 流 的 方法 
ngx_send_chain_pt send_chain; 

/* 这 个 连接 对 应 的 


ngx_listening_t 监 昕 对 象 ， 此 连接 


listening 监 听 端 口 的 事件 建立 


*/ 
ngx_listening t *listening; 
// 这 个 连接 上 已 经 发 送出 去 的 字 节 数 


off_t Sent ， 
// 可 以 记录 日 志 的 


ngx_log_t 对 象 
ngx_log_t *log; 
/* 内 存 池 。 一 般 在 


accept 一 个 新 连接 时 ， 会 创建 一 个 内 存 池 ， 而 在 这 个 连接 结束 时 会 销毁 内 存 池 。 注 意 ， 这 里 所 说 的 连接 是 指 成 
功 建立 的 


TCP 连 接 ， 所 有 的 
ngx_connection_t 结 构 体 都 是 预 分 配 的 。 这 个 内 存 池 的 大 小 将 由 上 面 的 


1istening 监 听 对 象 中 的 


pool_size 成 员 决定 

*/ 
ngx_pool _t *pool,; 
// 连接 客户 端的 


sockaddr 结 构 体 


struct sockaddr *sockaddr; 
// sockaddr 结 构 体 的 长 度 


socklen_t socklen, 
// 连接 客户 端 字 符 串 形式 的 


IP 地 址 


ngx_str_t addr_text; 
/* 本 机 的 监听 端口 对 应 的 


sockaddr 结 构 体 ， 也 就 是 


1istening 监 听 对 象 中 的 


sockaddr 成 员 
;人 

struct sockaddr *local sockaddr; 

/* 用 于 接收 、 缓 存 客户 端 发 来 的 字符 流 ， 每 个 事件 消费 模块 可 自由 决定 从 连接 池 中 分 配 多 大 的 空间 给 
buffer 这 个 接收 缓存 字段 。 例 如 ， 在 


HTTP 模 块 中 ， 它 的 大 小 决定 于 


client_header_buffer_size 配 置 项 


*/ 
ngx_buf_t *buffer; 
/* 该 字段 用 来 将 当前 连接 以 双向 链表 元 素 的 形式 添加 到 


ngx_cycle_t 核 心 结构 体 的 


altt 
i 
bay 
| 
了 
于 
| 
Sz 
和 
| 中 


的 连接 


reusable_connections_queue 双 向 链 姥 


4 
ngx_queue_t queue; 
/* 连 接 使 用 次 数 。 


' 端 的 连接 ， 或 者 用 于 主动 向 后 端 服务 器 发 起 连接 时 ( 


ngx_connection_t 结 构 体 每 次 建立 一 条 来 自 客 


鼠 | 


ngx_peer_connection_t 也 使 用 它 ) ， 
number 都 会 加 
1*/ 


ngx_atomic_uint_t number,; 


// 处 理 的 请 求 次 数 


ngx_uint_t requests; 
/* 缓 存 中 的 业务 类 型 。 任 何事 伯 


FE 消费 模块 都 可 以 自 定义 需要 的 标志 位 。 这 个 


buffered 字 段 有 


8 位 ， 最 多 可 以 同时 表示 


8 个 不 同 的 业务 。 第 三 方 模块 在 自 定 义 


以 
o 


buffered 标 志 位 时 注意 不 要 与 可 能 使 用 的 模块 定义 的 标志 位 冲突 。 目 前 


openss1 模 块 定义 了 一 个 标志 位 ; 


#define NGX_SSL_BUFFERED Ox01 
HTTP 官 方 模块 定义 了 以 下 标志 位 : 


#define NGX_HTTP_LOWLEVEL_BUFFERED Oxfg 

#define NGX_HTTP_WRITE_BUFFERED Ox10 

#define NGX_HTTP_GZIP_BUFFERED Ox20 

#define NGX_HTTP_SSI_BUFFERED Ox0O1 

#define NGX_HTTP_SUB_BUFFERED Ox02 

#define NGX_HTTP_COPY_BUFFERED Ox04 

#define NGX_HTTP_IMAGE_BUFFERED 0x08 同 时 ， 对 于 
HTTP 模 块 而 言 ， 

buffered 的 低 


4 位 要 慎 用 ， 在 实际 发 送 响 应 的 


ngx_http_write_filter_module 过 滤 模 块 中 ， 低 
4 位 标志 位 为 


1 则 意味 着 


Nginx 会 一 直 认 为 有 


HTTP 模 块 还 需要 处 理 这 个 请 求 ， 必 须 等 待 


HTTP 模 块 将 低 


4 位 全 置 为 


0 才 会 正常 结束 请 求 。 检 查 低 


4 位 的 宏 如 下 : 


#define NGX_ LOWLEVEL_ BUFFERED OxOf 
Wy 

unsigned buffered:8; 
/* 本 连接 记录 日 志 时 的 级 别 ， 它 占用 了 


3 位 ， 取 值 范围 是 


0~7， 但 实际 上 目前 只 定义 了 


5 个 值 ， 


ngx_connection_log_error_e 枚 举 表示 ， 如 下 : 


typedef enum { 
NGX_ERROR_ALERT = 0, 
NGX_ERROR_ERR, 
NGX_ERROR_INFO, 
NGX_ERROR_IGNORE_ECONNRESET, 
NGX_ERROR_IGNORE_EINVAL 
} ngx_connection_log_error_e; 
*/ 
unsigned log_ error:3,; 
/* 标 志 位 ， 为 


1 时 表示 独立 的 连接 ， 如 从 客户 端 发 起 的 连接 ， 为 


i 


上 


9 时 表示 依靠 其 他 连接 的 行为 而 建立 起 来 的 非 独立 连接 ， 如 使 


upstream 机 制 向 后 端 服务 器 建立 起 来 的 连接 
*/ 


unsigned single connection:1; 
// 标志 位 ， 为 


1 时 表示 不 期 竺 字符 流 结束 ， 目 前 无 意义 


unsigned unexpected eof:1; 
// 标志 位 ， 为 


长 示 连 接 已 经 超时 


| 


1 时 


unsigned timedout :1 
// 标志 位 ， 为 


1 时 表示 连接 处 理 过 程 中 出 现 错误 


unsigned error:1; 
/* 标 志 位 ， 为 


1 时 表示 连接 已 经 销毁 。 这 里 的 连接 指 是 的 


TCP 连 接 ， 而 不 是 


ngx_connection_t 结 构 体 。 
destroyed 为 


1 时 ， 


ngx_connection_t 结 构 体 仍然 存在 ， 但 其 对 应 的 套 接 字 、 内 存 池 等 已 经 不 可 用 


*/ 


a 


unsigned destroyed:1; 


/* 标 志 位 ， 为 


1 时 表示 连接 处 于 空闲 状态 ， 如 


keepalive 请 求 中 两 次 请 求 之 间 的 状态 


unsigned idle:1; 
// 标志 位 ， 为 


1 时 表示 连接 可 重用 ， 它 与 上 面 的 


queue 字 段 是 对 应 使 用 的 


unsigned reusable:1; 


// 标志 位 ， 为 


1 时 表示 连接 关闭 


unsigned close:1; 
// 标志 位 ， 为 


1 时 表示 正在 将 文件 中 的 数据 发 名 


unsigned sendfile:1; 


/* 标 志 位 ， 如 果 为 


连接 的 另 一 端 


Sl 


1， 则 表示 只 有 在 连接 套 接 字 对 应 的 发 送 缓冲 区 必须 满足 最 低 设 置 的 大 小 阀 值 时 ， 事 件 引 


件 。 这 与 上 文 介 绍 过 的 


ngx_handle_write_event 方 法 


lowat 参 数 是 对 应 的 


*/ 


unsigned sndlowat:1; 


/* 标 志 位 ， 表 示 如 何 使 月 


TCP 的 


nodelay 特 性 。 它 的 取 值 范围 


日 
征 


下 了 


的 


这 个 枚 举 类 型 


ngx_connection_tcp_nodelay_e: 


typedef enum { 


区 动 模 块 才 会 分 发 该 事 


NGX_TCP_NODELAY_UNSET = 0, 
NGX_TCP_NODELAY_SET， 
NGX_TCP_NODELAY_DISABLED 
} ngx_connection_tcp_nodelay_e; 
Wy 
unsigned tcp_nodelay:2; 
/* 标 志 位 ， 表 示 如 何 使 


TCP 的 


nopush 特 性 。 它 的 取 值 范围 是 下 面 这 个 枚 举 类 型 


ngx_connection_tcp_nopush_e: 


typedef enum { 
NGX_TCP_NOPUSH_UNSET = 0， 
NGX_TCP_NOPUSH_SET， 
NGX_TCP_NOPUSH_DISABLED 
} ngx_connection_tcp_nopush_e; 
*/ 
unsigned tcp_nopush:2; 
#if (NGX_HAVE_AIO_SENDFILE) 
// 标志 位 ， 为 


1 时 表示 使 用 异步 


I/0 的 方式 将 磁盘 上 文件 发 送 给 网 络 连 接 的 男 一 端 


unsigned aio_sendfile:1; 
// 使 用 异步 


I/0 方 式 发 送 的 文件 ， 


busy_sendfile 绥 冲 区 保存 待 发 送 文 件 的 信息 


ngx_buf_t *busy_sendfile; 
#endif 
}; 


链表 中 的 recv、send、recv_chain、send_chain 这 4 个 关于 接收 、 发 
送 网 络 字 符 流 的 方法 原型 定义 如 下 。 


typedef ssize t (*ngx_recv_pt)(ngx_connection t *c，U_char *buf，Size_t Size)， 
typedef ssize t (*ngx_recv_chain_ pt)(ngx_connection t *c, ngx_chain_t *in)， 
typedef ssize t (*ngx_send_ pt)(ngx_connection t *c, u_char *buf, size _t size); 
typedef ngx_chain_t *(*ngx_send_ chain_ pt)(ngx_connection_t *c, ngx_chain_t *in, 
off_t limit); 


这 4 个 成 员 以 方法 指针 的 形式 出 现 ， 说 明 每 个 连接 都 可 以 采用 不 同 
的 接收 方法 ， 每 个 事件 消费 模块 部 可 以 灵活 地 决定 其 行为 。 不 同 的 事 
件 驱 动机 制 需要 使 用 的 接收 、 发 送 方法 多 半 是 不 一 样 的 ， 在 9.6 节 中 ， 
读者 可 以 看 到 ngx_epoll_module 模 块 是 如 何 定 义 这 4 种 方法 的 。 


9.3.2 ”主动 连接 


作为 Web 服 务 器 ，Nginx 也 需要 癌 其 他 服务 器 主动 发 起 连接 ， 当 
然 ， 这 样 的 连接 与 上 一 节 介 绍 的 被 动 连 接 是 不 同 的 ， 它 使 用 
ngx_peer_connection_t 结 构 体 来 表示 主动 连接 。 不 过 ， 一 个 待 处 理 连 接 
的 许多 特性 在 被 动 连接 结构 体 ngx_connection_t 中 都 定义 过 了 ， 因 此 ， 
在 ngx_peer_connection_t 结 构 体 中 引用 了 ngx_connection_t 这 个 结构 体 ， 
下 面 我 们 来 看 一 下 其 定义 。 


typedef struct ngx_peer_connection s ngx_peer_connection_t; 
// 当 使 用 长 连接 与 上 游 服务 器 通信 有 时， 可 通过 该 方法 由 连接 池 中 获取 一 个 新 连接 


py ngx_int_t (*ngx_event get peer_pt) (ngx_peer_connection t *pc,void *data); 
/ 当 使 用 长 连接 与 上 游 服 务 器 通信 时 ， 通 过 该 方法 将 使 用 完毕 的 连接 释放 给 连接 池 


typedef void (*ngx_event_ free peer_pt) (ngx_peer_connection t *pc, void 
*data,ngx_uint_t state); 
struct ngx_peer_connection_s { 

/* 一 个 主动 连接 实际 上 也 需要 


ngx_connection_t 结 构 体 中 的 大 部 分 成 员 ， 并 且 出 于 重用 的 考虑 而 定义 了 


connection 成 员 


* 
ngx_connection_t *connection; 
// 远 端 服务 器 的 


socket 地 址 


Struct sockaddr *Ssockaddr 
// sockaddr 地 址 的 长 度 


socklen_t socklen; 


// 远 端 服务 器 的 名 称 


ngx_str_t *name; 


/* 表 示 在 连接 一 个 远 端 服务 器 时 ， 当 前 连接 出 现 异常 失败 后 可 以 重 试 的 次 数 ， 也 就 是 允许 的 最 多 失败 次 数 


*/ 

ngx_uint_t tries; 

// 获取 连接 的 方法 ， 如 果 使 用 长 连接 构成 的 连接 池 ， 那 么 必须 要 实现 
get 方 法 


ngx_event_get_peer_pt get; 
// 与 


get 方 法 对 应 的 释放 连接 的 方法 


ngx_event_free_peer_pt free,; 
/< 这 个 


data 指 针 仅 用 于 和 上 面 的 


get、 


free 方 法 配合 传递 参数 ， 它 的 具体 含义 与 实现 
get 方 法 、 
free 方 法 的 模块 相关 ， 可 参照 


ngx_event_get_peer_pt 和 


ngx_event_free_peer_pt 方 法 原型 中 的 


data 参 数 


* 
void *data; 


// 本 机 地 址 信息 


ngx_addr_t *local; 


// 套 接 字 的 接收 缓冲 区 大 小 


int rcvbuf; 
// 记录 日 志 的 


ngx_1og_t 对 象 


ngx_log_t *1log; 
// 标志 位 ,为 


1 时 表示 上 面 的 


connection 连 接 已 经 缓存 


unsigned cached :1， 
/ 


9.3.1 市 中 


ngx_connection_t 里 的 


1og_error 意 义 是 相同 的 ， 区 别 在 于 这 里 的 


i 
EA 


Pel 


1og_error 只 有 两 位 ， 只 


4 种 错误 ， 


NGX_ERROR_IGNORE_EINVAL 错 误 无 法 表达 


*/ 
unsigned 1og-error:2; 

ngx_peer_connection_t 也 有 一 个 ngx_connection_t 类 型 的 成 员 ， 怎 么 
理解 这 两 个 结构 体 之 间 的 关系 呢 ? 所 有 的 事件 消费 模块 在 每 次 使 用 
ngx_peer_connection_t 对 象 时 ， 一 般 都 需要 重新 生成 一 个 
ngx_peer_connection_t 结 构 体 ， 然 而 ，ngx_peer_connection_t 对 应 的 
ngx_connection_t 连 接 一 般 还 是 从 连接 池 中 获取 ， 因 此 ， 
ngX_peer_connection_t 只 是 对 ngx_connection_t 结 构 体 做 了 简单 的 包装 而 
= 


9.3.3 ngx_connection_t 连 接 池 


Nginx 在 接受 客户 器 的 连接 时 ， 所 使 用 的 ngx_connection_t 结 构 体 都 
征 在 司 动 阶段 束 预 分 配 好 的 ， 使 用 时 从 连接 池 中 获取 即 可 。 这 个 连接 
池 志 如何 封 猴 的 呢 ? 如 图 9-1 所 示 。 


从 图 9-1 中 可 以 看 出 ， 在 ngx_cycle_t 中 的 connections 和 
free_connections 这 两 个 成 员 构 成 了 一 个 连接 池 ， 其 中 connections 指 向 整 
个 连接 池 数 组 的 首部 ， 而 free_connections 则 指向 第 一 个 
ngx_connection_t 衬 采 和 连接。 所 有 的 空闲 连接 ngx_connection_t 都 以 data 
成 员 ( 见 9.3.1 节 ) 作为 next 指 针 串 联 成 一 个 单 链表 ， 如 此 ， 一 旦 有 用 户 
发 起 连 授 时 束 从 free_connections 指 疝 的 链表 头 获 取 一 个 空 几 的 连接 ， 同 
时 free_connections 再 指向 下 一 个 空闲 连接 。 而 归还 连接 时 只 需 把 该 连接 
插入 到 free_connections 链 表 表 头 即 可 。 


图 9-1 中 还 显示 了 事件 池 ，Nginx 认 为 每 一 个 连接 一 定 至 少 需要 一 个 
读 事 件 和 一 个 写 事 件 ， 有 多 少 连接 吏 分 本 多少 个 读 、 写 事件 。 怎 样 把 
连接 池 中 的 任 一 个 连接 与 读 事 件 、 写 事件 对 应 起 来 呢 ? 很 简单 。 由 于 
读 事件 、 写 事件 、 连 接 池 是 由 3 个 大 小 相同 的 数组 组 成 ， 所 以 根据 数组 
序号 就 可 将 每 一 个 连接 、 读 事件 、 写 事件 对 应 起 来 ， 这 个 对 应 关系 在 
ngx_event_core_module 模 块 的 初始 化 过 程 中 就 已 经 决定 了 (参见 9.5 
节 ) 。 这 3 个 数组 的 大 小 都 是 由 nginx.conf 中 的 connections 配 置 项 决定 
的 。 


在 使 用 连接 池 时 ，Nginx 也 封 半 了 两 个 方法 ， 见 表 9-1。 


如 采 我 们 开发 的 模块 直接 使 用 了 连接 池 ， 那 么 就 可 以 用 这 两 个 方 
法 来 获取 、 释 放 ngx_connection_t 结 构 体 。 


一 er 


free_connections 
+free_connection n 


TTT 训 TTTIT 
EE | 


1 
预 分 配 的 
connection _n 个 连接 | : ngx array_t 
1 :ngx array_t 
| +open files: ngx list t 
| +shared memory: ngx_list t 
1 1 +connection n 
人 +files mn 
TTT 国 TTTT py 
read events 
i write_events 
| 1 | +old_cycle 
预 分 配 的 | +conf file 
connection _n 个 读 事件 !_ | 


| 
| 
+ngx_master process cycle() 
[| 阐 \j|| | + ngx_single -process cycle() 
WE +ngx_start_ worker_processes() 
+ngx_ start cache manager processes() 
预 分 配 的 +ngx_pass open channel() 
connection n 个 写 事件 +ngx_ signal worker processes() 


ngx_reap children () 
master process exit() 
worker process cycle() 
worker process_init () 
worker_ process_exit() 
cache manager process cycle() 
process events and timers() 


在 connections 指 向 的 连接 池 
中 ， 每 个 连接 所 需要 的 读 / 写 
事件 都 以 相同 的 数组 序号 对 
应 着 read_events、write_events 
读 / 写 事件 数组 ， 相 同 序号 下 
这 3 个 数组 中 的 元 素 是 配合 使 
用 的 


图 9-1 ngx_connection_t 连 接 池 示意 图 
表 9-1 连接 池 的 使 用 方法 


连接 池 操 作 方 法 名 执行 意义 
nex_connection t *ngx get connection s 是 这 条 连接 的 套 接 字 句柄 , | 从 连接 池 中 获取 一 个 ngx_connection t 
(ngx_socket ts, ngx_ log t *log) log 则 是 记录 日 志 的 对 象 结构 体 ， 同 时 获取 相应 的 读 / 写 事件 
void ngx_free_connection Rk a 本 
多 到 c 是 需要 回收 的 连接 将 这 个 连接 回收 到 连接 池 中 


(ngx_connection t *c) 


9.4 ngx_events_module 核 心 模块 


ngx_events_module 模 块 是 一 个 核心 模块 ， 它 定义 了 一 类 新 模块 : 
事件 模块 。 它 的 功能 如 下 : 定义 新 的 事件 类 型 ， 并 定义 每 个 事件 模块 
都 需要 实现 的 ngx_event_module_t 接 口 (参见 9.1.1 节 ) ， 还 需要 管理 这 
些 事 件 模 块 生成 的 配置 项 结构 体 ， 并 解析 事件 类 配置 项 ， 当 然 ， 在 解 
析 配 置 项 时 会 调用 其 在 ngx_command_t 数 组 中 定义 的 回调 方法 。 这 些 过 
程 在 下 文中 都 会 介绍 ， 不 过 ， 首 先 还 是 看 一 下 ngx_events_module 模 块 
的 定义 。 


就 像 在 第 3 章 中 我 们 曾经 做 过 的 一 样 ， 定 义 一 个 Nginx 模 块 承 是 在 
实现 ngx_modult_t 结 构 体 。 这 里 需要 先 定义 好 ngx_command_t (决定 这 
个 模块 如 何 处 理 自 己 感 兴趣 的 配置 项 ) 数组， 因为 任何 模块 都 是 以 配 
置 项 来 定制 功能 的 。ngx_events_commands 数 组 决定 了 
ngx_events_module 模 块 是 如 何 定制 其 功能 的 ， 代 码 如 下 。 


static ngx_command t ngx_events commands[] = { 
{ ngx_string("events"), 
NGX_MAIN_CONF|NGX_CONF_BLOCK|NGX_CONF_NOARGS, 


ngx_events_block., 
09, 

09, 

NULL }, 

ngx_null command 


可 以 看 到 ，ngx_events_module 模 块 只 对 一 个 块 配 置 项 感 兴趣 ， 也 
就 是 nginx.conf 中 必须 有 的 events{.…} 配 置 项 。 注 意 ， 这 里 和 暂时 先 不 要 关 
心 ngx_events_block 方 法 是 如 何 处 理 这 个 配置 项 的 。 


作为 核心 模块 ，ngx_events_module 还 需要 实现 核心 模块 的 共同 接 
口 ngx_core_module t， 如 下 所 示 。 


static ngx_core module t ngx_events module ctx = { 
ngx_string("events"), 
NULL, 
NULL 

}; 


可 以 看 到 ，ngx_events_module_ctx 实 现 的 接口 只 是 定义 了 模块 名 字 
而 已 ，ngx_core_module_t 接 口中 定义 的 create_conf 方 法 和 init_conf 方 法 
都 没有 实现 (NULL 空 指针 即 为 不 实现 ) ， 为 什么 呢 ? 这 是 因为 
ngx_events_module 模 块 并 不 会 解析 配置 项 的 参数 ， 只 是 在 出 现 events 配 
置 项 后 会 调用 各 事件 模块 去 解析 events{...} 块 内 的 配置 项 ， 自 然 就 不 需 
要 实现 create_conf 方 法 来 创建 存储 配置 项 参数 的 结构 体 ， 也 不 需要 实现 
init_conf 方 法 处 理解 析出 的 配置 项 。 


最 后 看 一 下 ngx_events_module 模 块 的 定义 代码 如 下 。 


ngx_module_t ngx_events module = { 
NGX_MODULE_V1, 
&ngx_events module_ctx, 
ngx_events_commands, 
NGX_CORE_MODULE, 


* module context */ 
* module directives */ 


* module type */ 


i WR Te 
+ 


NULL, init master */ 
NULL, * jnit module */ 
NULL, * init process */ 
NULL, * jinit thread */ 


NULL, /* exit thread */ 
NULL, /* exit process */ 
NULL, /* exit master */ 
NGX_MODULE_V1_PADDING 


可 见 ， 除 了 对 events 配 置 项 的 解析 外 ， 该 模块 没有 做 其 他 任何 事 
情 。 下 面 开 始 介绍 在 解析 events 配 置 块 时 ，ngx_events_block 方 法 做 了 些 
什么 。 


9.4.1 如 何 管理 所 有 事件 模块 的 配置 项 


上 文 说 过 ， 每 一 个 事件 模块 都 必须 实现 ngx_event_module_t 接 口 ， 
这 个 接口 中 允许 每 个 事件 模块 建立 自己 的 配置 项 结构 体 ， 用 于 存储 感 
兴趣 的 配置 项 在 nginx.conf 中 对 应 的 参数 。ngx_event_module t 中 的 
create_conf 方 法 就 是 用 于 创建 这 个 结构 体 的 方法 ， 事 件 模块 只 需要 在 这 
个 方法 中 分 配 内 存 即 可 ， 但 这 个 内 存 指针 是 如 何 由 ngx_events_module 
模块 管理 的 呢 ? 下 面 来 看 一 下 这 些 事件 模块 的 配置 项 指针 是 如 何 被 存 
放 的 ， 如 图 9-2 所 示 。 


每 一 个 事件 模块 产生 的 配置 结构 体 指 针 都 会 被 放 到 
ngx_events_module 模 块 创建 的 指针 数组 中 ， 可 这 个 指针 数组 又 存放 到 
哪里 呢 ? 看 一 下 ngx_cycle_t 核 心 结构 体 中 的 conf_ctx 成 员 ， 它 指 癌 一 个 
指针 数组 ， 而 这 个 指针 数组 中 就 依次 存放 看 所 有 的 Nginx 模 块 天 于 配置 
项 方面 的 指针 。 在 默认 的 编译 顺序 下 ， 从 ngx_modules.c 文 件 中 可 以 看 
到 ngx_events_module 模 块 是 在 ngx_modules 数 组 中 的 第 4 个 位 置 ， 


此 ， 所 有 进程 的 conf_ctx 数 组 的 第 4 个 指针 就 保存 着 上 面 说 过 的 
ngx_events_module 模 块 创建 的 指针 数组 。 解 释 是 不 是 有 点 绕 ? 再 回顾 
一 下 ngx_cycle_t 结 构 体 中 的 conf_ctx 的 定义 : 


void ****conf_ctx; 


为 什么 上 面 代码 中 有 4 个 *? 因为 它 首 移 指 同一 个 存放 指针 的 数 
组 ， 这 个 数组 中 的 指针 成 员 同 时 又 指 癌 了 另外 一 个 存放 指针 的 数组 ， 
所 以 是 4 个 *。 看 到 conf_ctx 的 奥秘 了 吧 。 只 有 拥有 了 这 个 conf_ctx， 才 
可 以 看 到 任意 一 个 模块 在 create_conf 中 产生 的 结构 体 指针 。 同 理 ， 
HTTP 模 块 和 mail 模 块 也 是 这 样 做 的 ， 这 些 模块 的 通用 接口 中 也 有 
create_conf 方 法 ， 其 产生 的 指针 会 以 相似 的 方式 存放 。 


每 一 个 事件 模块 如 何 获取 它 在 create_conf 中 分 配 的 结构 体 的 指针 
呢 ? ngx_events_module 定 义 了 一 个 简单 的 宏 来 完成 这 个 功能 代码 ， 如 


#define ngx_event_get_ conf(conf_ctx,module 
(*(ngx_get_conf(conf_ctx, ngx_events module))) [module.ctx_index]; 


ngx_get_conf 也 是 一 个 宏 ， 它 用 来 获取 图 9-1 中 第 一 个 数组 中 的 指 
FS 0 


#define ngx_get_conf(conf_ctx, module) conf_ctx[module.index] 


因此 ， 调 用 ngx_event_get_conf 时 只 需要 在 第 1 个 参数 中 传 入 


ngx_cycle_t 中 的 conf_ctx 成 员 ， 在 第 2 个 参数 中 传 入 目 己 的 模块 名 ， 
构 体 的 指针 。 详 细 内 容 可 参见 9.6.3 节 中 使 用 


以 获取 配置 项 结 


束 可 


ngx_epoll_module 的 ngx_epoll_init 方 法 获取 配置 项 的 例子 。 


所 有 核心 模块 的 配置 结构 体 指针 


第 4 个 模块 是 ngx_ events module 
模块 ， 因 此 ， conf_ctx 数 组 ! 第 
位 存储 着 模块 的 配置 项 指针 ， ~ 
这 里 这 个 指针 定义 为 指向 另 一 
数组 

所 有 事 人 站 针 


事件 模块 1 中 create_conf 
方法 创建 的 结构 体 


事件 模块 2 中 create_conf 
方法 创建 的 结构 体 


事件 模块 3 中 create_conf | 
方法 创建 的 结构 体 


事件 模块 4 中 create_conf 


方法 创建 的 结构 体 


ngx cycle t 


+ free connections 

+ free connection _n 

+reusable_ connections _ queue :ngx queue s 
+listening : ngx array _t 

+pathes : ngx array _t 

+ open files: ngx list _t 

+ shared memory: ngx list_t 


+ connection _n 
+files _n 

+ connections 

+ read events 

+ Write _events 
+old_ cycle 
+conf file 

+ conf param 


+lock file 

+ hostname 

+ngx master process _cycle () 
+ngx single_ process _cycle () 
+ngx start worker processes () 

+ngx start _ cache manager processes() 
+ngx_pass_open channel () 

+ngx signal worker processes () 

+ngx reap_children () 

+ngx master process exit () 

+ ngx_worker_process_ cycle () 

+ ngx worker process_ init () 

+ ngx worker process_ exit () 

+ ngx cache manager process_cycle () 

+ ngx process events and timers () 


图 9-2 ”所 有 事件 模块 配置 项 结构 体 的 指针 是 如 何 管理 的 


9.4.2 管理 事件 模块 


上 文 说 到 ， 配 置 项 结构 体 指针 的 保存 都 是 在 ngx_events_block 方 法 
中 进行 的 。 下 面 再 来 看 一 下 这 个 方法 执行 的 流程 图 ， 如 图 9-3 所 示 。 


1 ) 初始 化 所 有 事件 模块 的 ctx __index 序号 


2 ) 分 配 指针 数组 ,存储 所 有 事件 模块 生成 的 配置 项 结构 体 指针 


3 ) 调用 所 有 事件 模块 的 create _conf 方法 


4 ) 为 所 有 事件 模块 解析 nginx . conf 配置 文件 


5 ) 调用 所 有 事件 模块 的 init _conf 方法 


全 


图 9-3 ngx_events_module 核 心 模 块 如 何 加 载 事件 模块 


下 面 简要 描述 一 下 这 5 个 步骤。 


1) 首先 初始 化 所 有 事件 模块 的 ctx_index 成 员 。 这 里 要 先 回顾 一 下 
ngx_module_t 模 块 接 口 的 定义 ， 如 下 所 示 。 
struct ngx module s { 


ngx_uint_t ctx_index; 
ngx_uint_t index; 


这 里 的 index 是 所 有 模块 在 ngx_modules.c 文 件 的 ngx_modules 数 组 中 
的 序号 ， 它 与 ngx_modules 数 组 中 所 有 模块 的 顺序 是 一 致 的 。 什 么 时 候 
初始 化 这 个 index 呢 ? 启动 Nginx 后 ， 在 调用 第 8 章 中 介绍 过 的 
ngx_init_cycle 方 法 前 束 会 进行 ， 代 码 如 下 。 
ngx_max_module = 0; 


for (i = 0; ngx_modules[i]; i++) { 
ngx_modules[i]->index = ngx_max_module+t+; 


其 中 ，ngx_max_module 是 Nginx 模 块 的 总 个 数 。 注 意 ， 本 书 前 文 曾 
多 次 提 到 过 ，Nginx 各 模块 在 ngx_modules 数 组 中 的 顺序 是 很 重要 的 ， 
依靠 index 成 员 ， 每 一 个 模块 才 可 以 把 目 己 的 位 置 与 其 他 模块 的 位 置 进 
行 比较 ， 并 以 此 决定 行为 。 但 是 ，Nginx 同 时 又 允许 再 次 定义 子 类 型 ， 
如 事件 类 型 、HTTP 类 型 、mail 类 型 ， 那 同一 类 型 的 模块 间 又 如 何 区 分 
顺序 呢 《依靠 index 当 然 可 以 区 分 顺序 ， 但 index 征 针对 所 有 模块 的 ， 这 
样 效率 太 差 ) ? 这 就 得 依靠 ctx_index 成 员 了 “。ctx_index 表 明了 模块 在 
相同 类 型 模块 中 的 顺序 。 


办 此 ，ngx_events_block 方 法 的 第 一 步 束 是 初始 化 所 有 事件 模块 的 
ctx_index 成 员 ， 这 会 决定 以 后 加 载 各 事件 模块 的 顺序 。 其 代码 非常 简 
单 ， 如 下 所 示 。 


ngx_event_max_module = 0; 
for (i = 0; ngx_modules[i]; i++) { 
If (ngx_modules[i]->type != NGX_EVENT_MODULE) { 
continue; 


ee = Ngx_event_max_module++; 
其 中 ，ngx_event_max_module 是 编译 进 Nginx 的 所 有 事件 模块 的 总 
个 数 。 
2) 分 配 9.4.1 节 中 介绍 的 指针 数组 ， 不 再 详 述 。 


3) 依次 调用 所 有 事件 模块 通用 接口 ngx_event_module t 中 的 
create_conf 方 法 ， 当 然 ， 产生 的 结构 体 的 指针 保存 在 上 面 的 指针 数组 
中 o 


4) 针对 所 有 事件 类 型 的 模块 解析 配置 项 。 这 时 ， 每 个 事件 模块 定 
义 的 ngx_command_t 决 定 了 配置 项 的 解析 方法 ， 如 果 在 nginx.conf 中 发 
现 相 应 的 配置 项 ， 就 会 回调 各 事件 模块 定义 的 方法 。 


5) 解析 完 配 置 项 后 ， 依 次 调用 所 有 事件 模块 通用 接口 
ngx_event_module_t 中 的 init_conf 方 法 ， 实 现 了 这 个 方法 的 事件 模块 可 
以 在 此 做 一 些 配 置 参 数 的 整合 工作 。 


以 上 束 是 ngx_events_module 模 块 的 核心 工作 流程 。 对 于 事件 驱动 
机 制 ， 更 多 的 工作 是 在 ngx_event_core_module 模 块 中 进行 的 ， 下 面 继续 
看 一 下 这 个 保 快 做 于 此 什么 六 


9.5 ngx_event_core_module 事 件 模块 


ngx_event_core_module 模 块 是 一 个 事件 类 型 的 模块 ， 它 在 所 有 事件 
模块 中 的 顺序 是 第 一 位 (configure 执 行 时 必须 把 它 放 在 其 他 事件 模块 之 
前 。 这 就 保证 了 它 会 先 于 其 他 事件 模块 执行 ， 由 此 它 选择 事件 驱动 
机 制 的 任务 才 可 以 完成 。 


ngx_event_core_module 模 块 要 完成 哪些 任务 呢 ? 它 会 创建 9.3 市 中 
介绍 的 连接 池 (包括 读 / 写 事件 ， 同 时 会 决定 究竟 使 用 哪些 事件 驱动 
机 制 ， 以 及 初始 化 将 要 使 用 的 事件 模块 。 


下 面 先 来 看 一 下 ngx_event_core_module 模 块 对 哪些 配置 项 感 兴趣 。 
该 模块 定义 了 ngx_event_core_commands 数 组 处 理 其 感 兴趣 的 7 个 配置 
项 ， 以 下 进行 简要 说 明 。 


static ngx_command t ngx_event core commands[] = { 


/* 连 接 池 的 大 小 ， 也 就 是 每 


worker 进 程 中 支持 的 


全 


TCP 最 大 连接 数 ， 它 与 下 面 的 


connections 配 置 项 的 意义 是 重复 的 ， 可 参照 


9.3.3 节 理解 连接 池 的 概念 


*/ 

{ ngx_string("worker_connections"), 
NGX_EVENT_CONF |NGX_CONF_TAKE1., 
ngx_event_connections, 

09, 
09, 


NULL }, 
// 连接 池 的 大 小 ， 与 


worker_connections 配 置 项 意义 相同 


{ ngx_string("connections"), 
NGX_EVENT_CONF |NGX_CONF_TAKE1., 
ngx_event_connections, 

09, 
09, 
NULL }, 
// 确定 选择 哪 一 个 事件 模块 作为 事件 驱动 机 制 


{ ngx_string("use"), 
NGX_EVENT_CONF |NGX_CONF_TAKE1., 
ngx_event_use, 

09, 
09, 

NULL }, 

/* 对 应 于 


9.2 节 中 提 到 的 事件 定义 的 


available 字 段 。 对 于 


epoll 事 件 驱 动 模式 来 说 ， 意 味 着 在 接收 到 一 个 新 连接 事件 时 ， 调 用 
accept 以 尽 可 能 多 地 接收 连接 


*/ 
{ ngx_string("multi accept"), 
NGX_EVENT_CONF |NGX_CONF_FLAG, 
ngx_conf_set_flag_slot, 

09, 
offsetof(ngx_event_conf_t, multi_accept), 
NULL }, 
// 确定 是 否 使 


CT 


衡 锁 ， 默 认为 


沸 
IJ 


accept_mutex 负 载 : 


{ ngx_string("accept_mutex"), 
NGX_EVENT_CONF |NGX_CONF_FLAG, 
ngx_conf_set_flag_slot, 

09, 
offsetof(ngx_event_conf_t, accept_mutex), 

NULL }, 


/* 启 


accept_mutex 负 载 均衡 锁 后 ， 延 迟 


hu 
六 
T™ 


accept_mutex_delay 毫 秒 后 再 试图 处 理 新 连接 习 


Wh 
{ ngx_string("accept_mutex_delay"), 
NGX_EVENT_CONF |NGX_CONF_TAKE1., 
ngx_conf_set_msec_slot, 
09, 
offsetof(ngx_event_ conf_t, accept_ mutex_delay), 
NULL }, 
// 需要 对 来 自 指定 


IP 的 


TCP 连 接 打印 


debug 级 别 的 调试 日 志 


{ ngx_string("debug_ connection"), 
NGX_EVENT_CONF |NGX_CONF_TAKE1., 
ngx_event_debug_connection, 

09, 

09, 

NULL }, 
ngx_null_command 


}; 


值得 注意 的 是 ， 上 面 对 于 配置 项 参数 的 解析 使 用 了 在 第 4 章 中 介绍 
过 的 Nginx 预 设 的 配置 项 解析 方法 ， 如 ngx_conf_set_flag_slot 和 
ngx_conf_set_msec_slot。 这 种 自动 解析 配置 项 的 方式 是 根据 指定 结构 
体 中 的 位 置 决定 的 。 下 面 看 一 下 该 模块 定义 的 用 于 存储 配置 项 参数 的 


结构 体 ngx_event_conf t。 


pedef struct { 
// 连接 池 的 大 小 


ngx_uint_t connections; 


/* 选 用 的 事件 模块 在 所 有 事件 模块 中 的 序号 ， 也 就 是 


9.4.2 节 中 介绍 过 的 


ctx_index 成 员 
*/ 
ngx_uint_t use,; 


// 标志 位 ， 如 果 为 


1， 则 表示 在 接收 到 一 个 新 连接 事件 时 ， 一 次 性 建立 尽 可 能 多 的 连接 


ngx_flag_t multi accept,; 
// 标志 位 ， 为 


1 时 表示 启用 负载 均衡 锁 


ngx_flag_t accept_mutex; 


/* 负 载 均衡 锁 会 使 有 些 
worker 进 程 在 拿 不 到 锁 时 延迟 建立 新 连接 ， 


accept_mutex_delay 就 是 这 段 延迟 时 间 的 长 度 。 关 于 它 如 何 影响 负载 均衡 的 内 容 ， 可 参见 
9.8.5 节 
二 


ngx_msec_t accept_mutex_delay 
// 所 选用 事件 模块 的 名 字 ， 它 与 


use 成 员 是 匹配 的 


u_char *name; 
#if (NGX_DEBUG) 
/* 在 一 


with-debug 编 译 模式 下 ， 可 以 仅 针对 某 些 客户 端 建立 的 连接 输出 调试 级 别 的 日 志 ， 而 


debug_connection 数 组 用 于 保存 这 些 客户 端的 地 址 信息 


A/ 

ngx_array_t debug_ connection; 
#endif 
} ngx_event_conf_t; 


ngx_event_conf t 结 构 体 中 有 两 个 成 员 与 负载 均衡 锁 相 关 ， 读 者 可 
以 在 9.8 节 中 了 解 负载 均衡 锁 的 原理 。 


对 于 每 个 事件 模块 都 需要 实现 的 ngx_event_module_t 接 口 ， 
ngx_event_core_module 模 块 则 仪 实现 了 create_conf 方 法 和 init_conf 方 
法 ， 这 是 因为 它 并 不 真正 负责 TCP 网 络 事件 的 驱动 ， 所 以 不 会 实现 
ngx_event_actions_t 中 的 方法 ， 如 下 所 示 。 


static ngx_str_t event_core_name = ngx_string("event_core"),; 
ngx_event_module t ngx_event core module ctx = { 
&event_core_name, 
ngx_event_create_conf ， /* create configuration */ 
ngx_event_init_conf, /* init configuration */ 
{ NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL } 


}; 


最 后 看 一 下 ngx_event_core_module 模 块 的 定义 。 


ngx_module t ngx_event_core_module = { 
NGX_MODULE_V1, 


&ngx_event_core_module_ctx, /* module context */ 
ngx_event_core_commands, /* module directives */ 
NGX_EVENT_MODULE， /* module type */ 

NULL, /* init master */ 
ngx_event_module_init, /* init module */ 
ngx_event_process_init, /* init process */ 
NULL, /* init thread */ 

NULL, /* exit thread */ 

NULL, /* exit process */ 
NULL, /* exit master */ 


,NoX_HoDuLE V1._PADDING 
它 实 现 了 ngx_event_module_init 方 法 和 ngx_event_process_init 方 

法 。 在 Nginx 启 动 过 程 中 还 没有 fork 出 worker 子 进程 时 ， 会 首先 调用 

ngx_event_core_module 模 块 的 ngx_event_module_init 方 法 (参见 图 8- 

6) ， 而 在 fork 出 worker 子 进程 后 ， 每 一 个 worker 进 程 会 在 调用 

ngx_event_core_module 模 块 的 ngx_event_process_init 方 法 后 才 会 进入 正 

式 的 工作 循环 。 弄 清楚 这 两 个 方法 何 时 调用 后 ， 下 面 来 看 一 下 它们 究 

况 做 了 什么 。 


ngx_event_module_init 方 法 其 实 很 集 单 ， 它 主要 初始 化 了 一 些 变 
量 ， 尤 其 是 ngx_http_stub_status_module 统 计 模 块 使 用 的 一 些 原 子 性 的 
统计 变量 ， 这 里 不 再 详 述 。 


而 ngx_event_process_init 方 法 就 做 了 许多 事情 ， 下 面 开始 详细 介绍 
它 的 流程 。 


ngx_event_core_module 模 块 在 启动 过 程 中 的 主要 工作 都 是 在 
ngx_event_process_init 方 法 中 进行 的 ， 如 图 9-4 所 示 。 


下 面 对 以 上 13 个 步骤 进行 商 要 说 明 。 


1) 当 打 开 accept_mnutex 负 载 均衡 锁 ， 同 时 使 用 了 master 模 式 并 且 
worker 进 程 数 量 大 于 1 时 ， 才 正式 确定 了 进程 将 使 用 accept_mnutex 人 负载 均 
衡山 。 因 此 ， 即 使 我 们 在 配置 文件 中 指定 打开 accept_mutex 锁 ， 如 采 没 
有 使 用 master 模 式 或 者 worker 进 程 数量 等 于 1， 进 程 在 运行 时 还 是 不 会 
使 用 负载 均衡 锁 《既然 不 存在 多 个 进程 去 抢 一 个 监听 端口 上 的 连接 的 
情况 ， 那 么 自然 不 需要 均衡 多 个 worker 进 程 的 负载 ) 


这 时 会 将 ngx_use_accept_mutex 全 局 变量 置 为 1， 
ngx_accept_mutex_held 标 志 设 为 0，ngx_accept_mutex_delay 则 设 为 在 配 
置 文件 中 指定 的 最 大 延迟 时 间 。 这 3 个 变量 的 意义 可 参见 9.8 节 中 关于 负 
载 均衡 锁 的 说 明 。 


2) 如 果 没 有 满足 第 1 步 中 的 3 个 条 件 ， 那 么 会 把 
ngx_use_accept_mnutex 置 为 0， 也 吏 是 关闭 负载 均衡 锁 。 


3) 初始 化 红 墨 树 实现 的 定时 器 。 关 于 定时 器 的 实现 细节 可 参见 9.6 
3 全 如 
4) 在 调用 use 配 置 项 指定 的 事件 模块 中 ， 在 ngx_event_module _{ 接 


口 下 ，ngx_event_actions_t 中 的 init 方 法 进行 这 个 事件 模块 的 初始 化 工 
作 。 


人 开 accept_mutex 配置 master 模 式 下 worker 进程 数量 大 于 ! ] 


1 ) 打 开 ngx_use accept_mutex 锁 


2) 关闭 ngx_use_accept_mutex 销 


3) 初始 化 红 黑 树 实现 的 
ngx_event_timer_rbtree 定 时 器 


4) 调用 use 配 置 项 指定 的 事件 驱动 模块 的 


init 方法 


[使 用 timer _resolution 设 置 了 时 间 精 度 ] 


5s) 指 定 timer_resolution 训 秒 后 调用 
ngx_timer_signal_handler 方 法 


[使 用 POLL 事 件 驱 动 ] 


6) 问 cycle 全 files 数组 预 分 配 运行 时 
使 用 的 连接 句柄 


7) 预 分 配 cycle 之 connections 


数组 充当 连接 池 


8) 预 分 配 所 有 读 事 作 到 


cycle 一 read_events 


9) 预 分 配 所 有 写 事件 到 


cycle 之 write_events 数组 


10) 将 上 述 SE 读 / 写 事件 放置 到 


connections 入 


11) 将 connetions 数组 的 连接 构成 单 链表 , 由 


cycle >free_connections 指向 空闲 连接 首 商 


12) 设置 监听 端口 上 读 事件 的 处 理 方 法 为 


ngx_event_accept 


13) 将 监听 连接 的 读 事件 添加 


到 事件 驱动 模块 


图 9-4 ngx_event_core_module 事 件 模块 启动 时 的 工作 流程 


5) 如 果 nginx.conf 配 置 文 件 中 设置 了 timer_resolution 配 置 项 ， 即 表 
明 需 要 控制 时 间 精 度 ， 这 时 会 调用 setitimer 方 法 ， 设 置 时间 间 隔 为 
timer_resolution 训 秒 来 回调 ngx_timer_signal_handler 方 法 。 下 面 简单 地 
介绍 一 下 Nginx 是 如 何 控制 时 间 精 度 的 。 


ngx_timer_signal_handler 方 法 又 做 了 些 什么 呢 ? 其 实 非 党 简单 ， 如 
下 所 示 。 


void ngx_timer_signal_handler(int signo) 


ngx_event_timer_alarm = 1; 


ngx_event_timer_alarm 只 是 个 全 局 变量 ， 当 它 设 为 1 时 ， 表 示 需 要 


更 新 时 间 。 


在 ngx_event_actions_t 的 process_events 方 法 中 ， 个 事件 驱动 模 
块 都 需要 在 ngx_event_timer_alarm 为 1 时 调用 ngx_time_update 方 法 ( 参 
见 9.7.1 节 ) 更 新 系统 时 间 ， 在 更 新 系统 结束 后 需要 将 


ngx_event_timer_alarm 设 为 0。 


6) 如 果 使 用 了 epoll 事 件 驱动 模式 ， 那 么 会 为 ngx_cycle_t 结 构 体 中 
的 files 成 员 预 分 配 句柄 。 本 章 仅 针对 epol 事 件 驱动 模式 ， 具 体内 容 不 再 


7) 预 分 配 ngx_connection_t 数 组 作为 连接 池 ， 同 时 将 ngx_cycle_t 结 
构 体 中 的 connections 成 员 指 回 该 数组 。 数 组 的 个 数 为 nginx.conf 配 置 文 
件 中 connections 或 worker_connections 中 配置 的 连接 数 。 


8) 预 分 配 ngx_event_t 事 件数 组 作为 读 事件 池 ， 同 时 将 ngx_cycle 
结构 体 中 的 read_events 成 员 指 同 该 数组 。 数 组 的 个 数 为 nginx.conf 配 置 
文件 中 connections 或 worker_connections 里 配置 的 连接 数 。 


9) 预 分 配 ngx_event_t 事 件数 组 作为 写 事件 池 ， 同 时 将 ngx_cycle_t 
结构 体 中 的 write_events 成 员 指 回 该 数组 。 数 组 的 个 数 为 nginx.conf 配 置 
文件 中 connections 或 worker_connections 里 配置 的 连接 数 。 


10) 按照 序号 ， 将 上 述 3 个 数组 相应 的 读 / 写 事件 设置 到 每 一 个 
ngx_connection_t 连 接 对 象 中 ， 同 时 把 这 些 连 接 以 ngx_connection_t 中 的 
data 成 员 作 为 next 指 针 串 联 成 链表 ， 为 下 一 步 设置 空间 连接 链表 做 好 准 
备 ， 参 见 图 9-1。 


11) 将 ngx_cycle_t 结 构 体 中 的 空 朵 连接 链表 free_connections 指 向 
connections 数 组 的 最 后 1 个 元 素 ， 也 就 是 第 10 步 所 有 ngx_connection_t 连 
接 通 过 data 成 员 组 成 的 单 链表 的 首部 。 


12) 在 刚刚 建立 好 的 连接 池 中 ， 为 所 有 ngx_jlistening_t 监 听 对 象 中 
的 connection 成 员 分 配 连 接 ， 同 时 对 监听 端口 的 读 事件 设置 处 理 方法 为 


ngx_event_accept， 也 就 是 说 ， 有 新 连接 事件 时 将 调用 ngx_event_accept 
方法 建立 新 连接 〈 详 见 9.8 节 中 关于 如 何 建立 新 连接 的 内 容 ) 。 


13) 将 监听 对 象 连接 的 读 事件 添加 到 事件 驱动 模块 中 ， 这 样 ， 
epoll 等 事件 模块 束 开 始 检测 监听 服务 ， 并 开始 辐 用 户 提 供 服 务 了 。 注 
意 ， 打 开 accept_mnutex 氏 后 则 不 执行 这 一 步 。 


至 此 ，ngx_event_core_module 模 块 的 启动 工作 就 全 部 结束 了 。 下 面 
将 以 epoll 事 件 方式 为 例 来 介绍 实际 的 事件 驱动 模块 是 如 何 处 理事 件 
的 。 


9.6 ”epoll 事 件 驱 动 檬 块 


本 半 9.1 和 ~9.5 节 都 在 探讨 Nginx 是 如 何 设计 事件 驱动 框架 、 如 何 管 
理 不 同 的 事件 驱动 模块 的 ， 但 本 三 中 将 以 epoll 为 例 ， 讨 论 Linux 操 作 系 
统 内 核 症 如 何 实现 epoll 事 件 驱 动机 制 的， 在 简单 了 解 它 的 用 法 后 ， 会 
进一步 说 明 ngx_epoll_module 模 块 是 如 何 基于 epoll 实 现 Nginx 的 事件 驱 
动 的 。 这 样 读者 就 会 对 Nginx 完 整 的 事件 张 动 设计 方法 有 全 面 的 了 解 ， 
同时 可 以 弄 清楚 Nginx 在 儿 十 万 并 发 连接 下 是 如 何 做 到 高 效 利用 服务 器 
资源 的 。 


9.6.1 ”epoll 的 原理 和 用 法 


设想 一 个 场景 ， 有 100 万 用 户 同 时 与 一 个 进程 保持 看 TCP 连 授 ， 而 
每 一 时 刻 只 有 几 十 个 或 几 百 个 TCP 连 接 是 活跃 的 接收 到 TCP 包 ) ， 也 
就 是 说 ， 在 每 一 时 刻 ， 进 程 只 需要 处 理 这 100 万 连接 中 的 一 小 部 分 连 
接 。 那 么 ， 如 何 才能 高 效 地 处 理 这 种 场景 呢 ? 进程 是 否 在 每 次 询问 操 
作 系 统 收集 有 事件 发 生 的 TCP 连 接 时 ， 把 这 100 万 个 连接 告诉 操作 系 
统 ， 然 后 由 操作 系统 找 出 其 中 有 事件 发 生 的 几 百 个 连接 呢 ? 实际 上 ， 
在 Linux 内 核 2.4 版 本 以 前 ， 那 时 的 select 或 者 poll 事 件 驱 动 方式 就 是 这 样 
做 的 。 


这 里 有 个 非常 明显 的 问题 ， 即 在 某 一 时 刻 ， 进 程 收 集 有 事件 的 连 
接 时 ， 其 实 这 100 万 连接 中 的 大 部 分 都 是 没有 事件 发 生 的 。 因 此 ， 如 果 
每 次 收集 事件 时 ， 都 把 这 100 万 连接 的 套 接 字 传 给 操作 系统 (这 首先 就 
是 用 户 态 内 存 到 内 核 态 内 存 的 大 量 复制 ) ， 而 由 操作 系统 内 核 寻找 这 
些 连接 上 有 没有 未 处 理 的 事件 ， 将 会 是 巨大 的 资源 浪费 ， 然 而 select 和 
poll 束 是 这 样 做 的 ， 因 此 它们 最 多 只 能 处 理 几 千 个 并 发 连 授 。 而 epoll 不 
这 样 做 ， 它 在 Linux 内 核 中 申请 了 一 个 简易 的 文件 系统 ， 把 原先 的 一 个 
select 或 者 poll 调 用 分 成 了 3 个 部 分 :调用 epoll_create 建 并 1 个 epoll 对 象 

(在 epoll 文 件 系统 中 给 这 个 句柄 分 配 资源 ) 、 调 用 epoll_ctl 向 epol 对 象 
中 添加 这 100 万 个 连接 的 僚 接 字 、 调 用 epoll_wait 收 集 发 生 事件 的 连接 。 
这 样 ， 只 需要 在 进程 启动 时 建立 1 个 epoll 对 象 ， 并 在 需要 的 时 候 疝 它 添 
加 或 删除 连接 就 可 以 了 ， 因 此 ， 在 实际 收集 事件 时 ，epoll_wait 的 效率 
就 会 非常 高 ， 因 为 调用 epoll_wait 时 并 没有 向 它 传递 这 100 万 个 连接 ， 内 
核 也 不 需要 去 电 历 全 部 的 连接 。 


那么 ，Linux 内 核 将 如 何 实现 以 上 的 想法 呢 ? 下 面 以 Linux 内 核 
2.6.35 版 本 为 例 ， 简 单 说明 一 下 epoll 是 如 何 高 效 处 理事 件 的 。 图 9-5 展 示 
了 epoll 的 内 部 主要 数据 结构 古 如 何 安排 的 。 


当 某 一 个 进程 调用 epoll_create 方 法 时 ，Linux 内 核 会 创建 一 个 
eventpoll 结 构 体 ， 这 个 结构 体 中 有 两 个 成 员 与 epoll 的 使 用 方式 密切 相 
关 ， 如 下 所 示 。 


struct eventpoll { 


/* 红 黑 树 的 根 节点 ， 这 棵 树 中 存储 着 所 有 添加 到 


epol1 中 的 事件 ， 也 就 是 这 个 


epol1 监 控 的 事 


汗 


了 


Struct rb_root rbr， 
// 双向 链表 


rdllist 保 存 着 将 要 通过 


epo11_wait 返 回 给 用 户 的 、 满 足 条 件 的 事 


}; 


这 


struct list_head rdllist,; 


eventpoll 


红 黑 树 中 每 个 节点 都 | 
是 基于 epitem 结 构 中 + poll_wait 


+ rdllist 
的 rdllink 成 员 


红 黑 树 中 0 
每 个 节点 
都 是 基于 +nwait 
性 epitem 结 +Pwdlist 
S 
辣 中 的 ink 
() rbn 成 员 +event 


图 9-5 epoll 原 理 示 意图 


每 一 个 epoll 对 象 都 有 一 个 独立 的 eventpoll 结 构 体 ， 这 个 结构 体会 在 
内 核 空间 中 创造 独立 的 内 存 ， 用 于 存储 使 用 epoll_ctl 方 法 向 epoll 对 象 中 
添加 进来 的 事件 。 这 些 事 件 都 会 挂 到 rbr 红 黑 树 中 ， 这 样 ， 重 复 添 加 的 
事件 就 可 以 通过 红 黑 树 而 高 效 地 识别 出 来 (epoll_ctl 方 法 会 很 快 ) 。 
Linux 内 核 中 的 这 棵 红 黑 树 与 第 7 章 中 介绍 的 Nginx 红 黑 树 是 非常 相似 
的 ， 可 以 参照 hgx_rbtree_t 容 器 进行 理解 。 


所 有 添加 到 epoll 中 的 事件 都 会 与 设备 (如 网 卡 ) 驱动 程序 建立 回 
调 关 系 ， 也 就 是 说 ， 相 应 的 事件 发 生 时 会 调用 这 里 的 回调 方法 
回调 方法 在 内 核 中 叫做 ep_poll_callback， 它 会 把 这 样 的 事件 放 到 上 面 的 
rdllist 双 向 链表 中 。 这 个 内 核 中 的 双向 链表 与 ngx_queue_t 容 器 儿 乎 是 
全 相同 的 (Nginx 代 码 与 Linux 内 核 代码 很 相似 ) ， 我 们 可 以 参照 着 理 
解 。 在 epoll 中 ， 对 于 每 一 个 事件 都 会 建立 一 个 epitem 结 构 体 ， 如 下 所 


不 。 


struct epitem { 


// 红 黑 树 节点 ， 与 第 


7 章 中 的 


ngx_rbtree_node_t 红 黑 树 节点 相似 


struct rb_node rbn; 
// 双向 链表 节点 


7 章 中 的 


ngx_queue_t 双 向 链表 节点 相似 


struct list_head rdllink; 
// 事件 句柄 等 信息 


Struct epoll filefd ffd， 
// 指向 其 所 属 的 


eventpoll 对 象 


Struct eventpoll *ep,; 
// 期 待 的 事件 类 型 


Struct epoll event event 


这 里 包含 每 一 个 事件 对 应 着 的 信息 。 


当 调 用 epoll_wait 检 查 是 否 有 发 生 事件 的 连接 时 ， 只 是 检查 
eventpoll 对 和 象 中 的 rdllist 双 向 链表 是 否 有 epitem 元 素 而 已 ， 如 果 rdllist 链 
表 不 为 衬 ， 则 把 这 里 的 事件 复制 到 用 户 态 内 存 中 ， 同 时 将 事件 数量 返 
回 给 用 户 。 因 此 ，epoll_wait 的 效率 非常 高 。epoll_ctl 在 向 epoll 对 象 中 添 
加 、 修 改 、 删 除 事 件 时 ， 从 rbr 红 黑 树 中 查找 事件 也 非常 快 ， 也 就 是 
说 ，epol] 是 非常 高 效 的 ， 它 可 以 轻易 地 处 理 百 万 级 别 的 并 发 连接 。 


9.6.2 ”如 何 使 用 epoll 


epoll 通 过 下 面 3 个 epoll 系 统 调用 为 用 户 提供 服务 。 


(1) epoll_create 系 统 调用 


epoll_create 在 C 库 中 的 原型 如 下 。 


int epoll create(int size); 


epoll_create 返 回 一 个 句柄 ， 之 后 epoll 的 使 用 都 将 依靠 这 个 句柄 来 标 
识 。 参 数 size 是 告诉 epol 所 要 处 理 的 大 致 事件 数目 。 不 再 使 用 epoll 时 ， 
必须 调用 close 关 闭 这 个 句柄 。 


人 @@ 注意 size 参数 只 是 告诉 内 核 这 个 epol 对 象 会 处 理 的 事件 大 致 
数目 ， 而 不 是 能 够 处 理 的 事件 的 最 大 个 数 。 在 Linux 最 新 的 一 些 内 核 版 
本 的 实现 中 ， 这 个 size 参 数 没 有 任何 意义 。 


(2) epoll_ctl 系 统 调 用 


epoll_ct 在 C 库 中 的 原型 如 下 。 


int epoll_ctl(int epfd, int op,int fd,struct epol]l_event* event ) ; 


epoll_ct 回 epol 对 象 中 添加 、 修 改 或 者 删除 感 兴趣 的 事件 ， 返 回 0 
表示 成 功 ， 否 则 返回 -1， 此 时 需要 根据 ermo 错 误 码 判断 错误 类 型 。 
epoll_wait 方 法 返回 的 事件 必然 是 通过 epoll_ctl 添 加 到 epoll 中 的 。 参 数 
epfd 是 epoll_create 返 回 的 句柄 ， 而 op 参数 的 意义 见 表 9-2。 


表 9-2 epoll_ctl 系 统 调用 中 第 2 个 参数 的 取 值 意义 


op 的 取 值 意 义 
EPOLL CTL ADD 添加 新 的 事件 到 epoll 中 
EPOLL CTL MOD 修改 epoll 中 的 事件 
EPOLL CTL DEL 删除 epoll 中 的 事件 


第 3 个 参数 fq 是 待 监 测 的 连接 套 接 字 ， 第 4 个 参数 是 在 告 op 
么 样 的 事件 感 兴趣 ， 它 使 用 了 epoll_event 结 构 体 ， 在 上 文 介 绍 过 的 epoll 
实现 机 制 中 会 为 每 一 个 事件 创建 epitem 结 构 体 ， 而 在 epitem 中 有 一 个 
epoll_event 类 型 的 event 成 员 。 下 面 看 一 下 epoll_event 的 定义 。 


struct epoll event{ 
__Uint32_t events,; 
epoll data t data; 


}; 


events 的 取 值 见 表 9-3。 


表 9-3 ”epoll_event 中 events 的 取 值 意义 


events 取 值 意 义 

TT 表示 对 应 应 的 连接 上 ne (TCP 连接 的 远 端 主动 关闭 连接 ， 也 相当 于 可 读 事 件 ， 

因为 需要 处 理发 送 来 的 FIN 包 ) 
_ 表示 对 应 的 连接 上 可 以 写 和 数据 发 送 (主动 向 上 游 服务 器 发 起 非 阻 塞 的 TCP 连接， 连接 

EPOLLOUT AR 
建立 成 功 的 事件 相当 于 可 写 事件 ) 

EPOLLRDHUP 表示 TCP 连接 的 远 端 关闭 或 半 关 闭 连 接 

EPOLLPRI 表示 对 应 的 连接 上 有 紧急 数据 需要 读 

EPOLLERR 表示 对 应 的 连接 发 生 错 误 

EPOLLHUP 表示 对 应 的 连接 被 挂 起 

EPOLLET 表示 将 触发 方式 设置 为 边缘 触发 (ET)， 系 统 默认 为 水 平 触 发 (LT) 

EPOLLONESHOT 表示 对 这 个 事件 只 处 理 一 次 ， 下 次 需要 处 理 时 需 重 新 加 入 epoll 


而 data 成 员 是 一 个 epoll_data 联 合 ， 其 定义 如 下 。 


typedef union epoll data { 
void *ptr; 


int fd; 

Uint32_t U32 ， 

uint64 七 u64; 
} epoll data t; 


可 见 ， 这 个 data 成 员 还 与 具体 的 使 用 方式 相关 。 例 如 ， 
ngx_epoll_module 模 块 只 使 用 了 联合 中 的 ptr 成 员 ， 作 为 指 问 
ngx_connection_t 连 接 的 指针 。 


(3) epoll_wait 系 统 调用 


epoll_wait 在 C 库 中 的 原型 如 下 。 


int epoll] wait(int epfd,struct epoll event* events,int maxevents,int timeout); 


收集 在 epoll 监 控 的 事件 中 已 经 发 生 的 事件 ， 如 果 epoll 中 没有 任何 
一 个 事件 发 生 ， 则 最 多 等 待 tmeout 毫 秒 后 返回 。epoll_wait 的 返回 值 表 
示 当 前 发 生 的 事件 个 数 ， 如 采 返 回 0， 则 表示 本 次 调用 中 没有 事件 发 
生 ， 如 果 返 回 -1， 则 表示 出 现 错误 ， 需 要 检查 errno 错 误 码 判断 错误 类 
型 。 第 1 个 参数 epfd 是 epoll 的 摘 述 从 。 第 2 个 参数 events 则 是 分 配 好 的 
epoll_event 结 构 体 数组 ，epoll 将 会 把 发 生 的 事件 复制 到 events 数 组 中 
(events 不 可 以 是 空 指针 ， 内 核 只 负责 把 数据 复制 到 这 个 events 数 组 
中 ， 不 会 去 帮助 我 们 在 用 户 态 中 分 配 内 存 。 内 核 这 种 做 法 效率 很 
高 ) 。 第 3 个 参数 maxevents 表 示 本 次 可 以 返回 的 最 大 事件 数目 ， 通 常 
maxevents 参 数 与 预 分 配 的 events 数 组 的 大 小 是 相等 的 。 第 4 个 参数 


timeout 表 示 在 没有 检测 到 事件 发 生 时 最 多 等 待 的 时 间 〈 单 位 为 这 


秒 ) ， 如 果 timeout 为 0， 则 表示 epoll_wait 在 rdllist 链 表 中 为 空 ， 立 刻 返 
回 ， 不 会 等 待 。 


epol 有 两 种 工作 模式 : LT (水 平 触发 ) 模式 和 ET (边缘 触发 ) 模 
式 。 默 认 情 况 下 ，epol 和 采用 LI 模式 工作 ， 这 时 可 以 处 理 阻 塞 和 非 阻塞 
套 接 字 ， 而 表 9-3 中 的 EPOLLET 表 示 可 以 将 一 个 事件 改 为 ET 模式 。ET 
模式 的 效率 要 比 LT 模 式 高 ， 它 只 文 持 非 阻塞 套 接 字 。EIT 模 式 与 LI 模式 
的 区 别 在 于 ， 当 一 个 新 的 事件 到 来 时 ，ET 模 式 下 当然 可 以 从 epoll_wait 
调用 中 获取 到 这 个 事件 ， 可 是 如 果 这 次 没有 把 这 个 事件 对 应 的 套 接 字 
缓冲 区 处 理 完 ， 在 这 个 套 接 字 没 有 新 的 事件 再 次 到 来 时 ， 在 ET 模式 下 
是 无 法 再 次 从 epoll_wait 调 用 中 获取 这 个 事件 的 ， 而 LI 模式 则 相反 ， 只 
要 一 个 事件 对 应 的 套 接 字 缓 冲 区 还 有 数据 ， 就 总 能 从 epoll_wait 中 获取 
这 个 事件 。 因 此 ， 在 LI 模式 下 开发 基于 epoll 的 应 用 要 简单 一 些 ， 不 太 
容易 出 错 ， 而 在 ET 模式 下 事件 发 生 时 ， 如 果 没 有 彻底 地 将 缓冲 区 数据 
处 理 完 ， 则 会 导致 缓冲 区 中 的 用 户 请 求 得 不 到 响应 。 默 认 情 况 下 ， 
Nginx 是 通过 ET 模式 使 用 epol 的 ， 在 下 文中 就 可 以 看 到 相关 内 容 。 


9.6.3 ngx_epoll_module 模 块 的 实现 


本 蔬 主 要 介绍 事件 张 动 模块 接口 与 epol 用 法 是 如 何 结合 起 来 发 挥 
作用 的 。 首 先 看 一 下 ngx_epoll_module 模 块 究竟 对 哪些 配置 项 感 兴趣 ， 
其 中 ngx_epoll_commands 数 组 指明 了 影响 其 可 定制 性 的 两 个 配置 项 。 


static ngx_command t ngx_epoll commands[] = { 


/* 在 调用 


nl 


epoll_waitH 时 ， 将 由 第 
2 和 第 


3 个 参数 告诉 


Linux 内 核 一 次 最 多 可 返回 多 少 个 事件 。 这 个 配置 项 表示 调用 一 次 


epo1l1_wait 时 最 多 可 以 返回 的 事件 数 ， 当 然 ， 它 也 会 预 分 配 那么 多 


epo1l1_event 结 构 体 用 于 存储 事件 


*/ 

{ ngx_string("epoll events"), 
NGX_EVENT_CONF |NGX_CONF_TAKE1., 
ngx_conf_set_num_slot, 

09, 
offsetof(ngx_epoll conf_t, events), 
NULL }, 
/* 指 明 在 开启 异步 


I/0 且 使 


io_setup 系 统 调用 初始 化 异步 
I/0 上 下 文 环境 时 


;初始 分 配 的 异步 


I/0 事 件 个 数 ， 详 见 


{ ngx_string("worker_aio_requests"), 
NGX_EVENT_CONF |NGX_CONF_TAKE1., 
ngx_conf_set_num_slot, 

09, 
offsetof(ngx_epoll conf_t, aio_requests), 
NULL }, 
ngx_null_ command 


}; 


上 面 使 用 了 预 分 配 的 ngx_conf_set_num_slot 方 法 来 解析 这 两 个 配置 
项 ， 下 面 看 一 下 存储 配置 项 的 结构 体 ngx_epoll_conf t。 


ngx_epoll conf_t。 


typedef struct { 
ngx_uint_t events; 


ngx_uint_t alio_requests 
} ngx_epoll conf_t; 


其 中 ，events 是 调用 epoll_wait 方 法 时 传 入 的 第 3 个 参数 maxevents， 
而 第 2 个 参数 events 数 组 的 大 小 也 是 由 它 决 定 的 ， 下 面 将 在 
ngx_epoll_init 方 法 中 初始 化 这 个 数组 。 


接 下 来 看 一 下 epoll 是 如 何 定 义 ngx_event_module_t 事 件 模块 接口 
的 ， 代 码 如 下 。 


static ngx_str_t epoll name = ngx_string("epoll"); 
ngx_event_module _t ngx_epoll] module ctx = { 
&epoll_name, 
ngx_epoll create_conf, 
ngx_epoll_init_conf, 


// 对 应 于 


ngx_event_actions_t 中 的 


add 方 法 


ngx_epoll add event, 
// 对 应 于 


ngx_event_actions_t 中 的 


del 方 法 


ngx_epol]l] del event, 
// 对 应 于 


ngx_event_actions_t 中 的 
enable 方 法 ， 与 
add 方 法 一 致 


ngx_epoll_ add_event, 
// 对 应 于 


ngx_event_actions_t 中 的 
disable 方 法 , 与 


del 方 法 一 致 


ngx_epoll del_event, 
// 对 应 于 


ngx_event_actions_t 中 的 


add_conn 方 法 


ngx_epoll add_connection, 
// 对 应 于 


ngx_event_actions_t 中 的 


del_conn 方 法 
ngx_epoll del_connection, 
// 未 实现 

ngx_event_actions_t 中 的 

process_changes 方 法 


NULL, 
// 对 应 于 


ngx_event_actions_t 中 的 


process_events 方 法 


ngx_epoll_process_events, 
// 对 应 于 


ngx_event_actions_t 中 的 


init 方 法 


ngx_epoll_init, 
// 对 应 于 


ngx_event_actions_t 中 的 


done 方 法 


ngx_epoll_done, 


}; 


其 中 ，ngx_epoll_create_conf 方 法 和 ngx_epoll_init_conf 方 法 只 是 为 
了 解析 配置 项 ， 略 过 不 所， 下 面 重点 看 一 下 ngx_event_actions_t 中 的 10 


个 接口 是 如 何 实现 的 。 


首先 从 实现 init 接 口 的 ngx_epoll_init 方 法 讲 起 。ngx_epoll-init 方 法 是 
在 什么 时 候补 调用 的 呢 ? 在 图 9-4 的 第 4 步 中 它 会 彼 调 用 ， 也 束 是 Nginx 
的 启动 过 程 中 。ngx_epoll_init 方 法 主要 做 了 两 件 事 : 


1) 调用 epoll_create 方 法 创建 epoll 对 象 。 


2) 创建 event_list 数 组 ， 用 于 进行 epoll_wait 调 用 时 传递 内 核 态 的 事 
件 。 


event_list 数 组 就 是 用 于 在 epoll_wait 调 用 中 接收 事件 的 参数 ， 如 下 
所 示 。 


static int ep = -1; 
static struct epoll event *event_list,; 
static ngx_uint_t nevents; 


其 中 ，ep 是 epoll 对 和 象 的 描述 符 ，nevents 是 上 面 说 到 的 epoll_events 
配置 项 参数 ， 它 既 指 明了 epoll_wait 一 次 返回 的 最 大 事件 数 ， 也 告诉 了 
event_jist 应 该 分 配 的 数组 大 小 。ngx_epoll_init 方 法 代码 如 下 所 示 。 


static ngx_int_t ngx_epoll init(ngx_cycle t *cycle, ngx_msec_t timer ) 


ngx_epoll conf_t *epcf,; 
/* 获 取 


create_conf 中 生成 的 


ngx_epol1_conf _t 结 构 体 ， 它 已 经 被 赋予 解析 完 配置 文件 后 的 值 。 详 细 内 容 可 参见 


9.4.1 市 中 关于 


ngx_event_get_conf 宏 的 用 法 


* 
/ 
epcf = ngx_event_get_conf(cycle->conf_ctx, ngx_epoll module); 
if (ep == -1) { 
/* 调 


epoll_create 在 内 核 中 创建 


epol11 对 象 。 上 文 已 经 讲 过 ， 参 数 


size 不 是 用 于 指明 


epol1 能 够 处 理 的 最 大 事件 个 数 ， 因 为 在 许多 


UD 


Linux 内 核 版 本 中 ， 


epol1 是 不 处 理 这 个 参数 的 ， 所 以 设 为 


cycle-> connection_n/2 (而 不 是 


cycle->connection_n) 也 不 要 紧 


二 
ep = epoll create(cycle->connection_n/2); 
if (ep == -1) { 
ngx_log_error(NGX_LOG_ EMERG, cycle->log, ngx_errno, 
"epoll create() failed"); 
return NGX_ERROR; 


} 
#if (NGX_HAVE_FILE AIO) 


// 异步 
I/0 内 容 可 参见 
9.9 市 
ngx_epoll aio_init(cycle, epcf); 
#endif 
} 


if (nevents < epcf->events) { 
if (event_ list) { 
ngx_free(event_list); 


} 
// 初始 化 


event_1ist 数 组 。 数 组 的 个 数 是 配置 项 


epoll_events 的 参数 


event_list = ngx_alloc(sizeof(struct epoll event) * epcf->events, cycle- 


>10g); 
If (event_list == NULL) { 
return NGX_ERROR; 
} 
} 


// ”nevents 也 是 配置 项 


epoll_events 的 参数 


nevents = epcf->events,; 
// 指明 读 写 


I/0 的 方法 ， 本 章 不 做 具体 说 明 


ngx_io = ngx_os_io; 
// 设置 


ngx_event_actions 接 


ngx_event_actions = ngx_epoll module ctx.actions,; 
#if (NGX_HAVE_CLEAR_EVENT ) 
/* 默 认 是 采 


ET 模式 来 使 


epol1 的 ， 


NGX_USE_CLEAR_EVENT 宏 实际 上 就 是 在 告诉 


Nginx 使 


ET 模式 
wh 
ngx_event_flags = NGX_USE_CLEAR_EVENT 
#else 
ngx_event_flags = NGX_USE_LEVEL_EVENT 
#endif 
|NGX_USE_GREEDY_EVENT 
|NGX_USE_EPOLL_EVENT 
return NGX_OK， 


ngx_event_actions 是 在 Nginx 事 件 框 架 处 理事 件 时 封装 的 接口 ， 我 
们 会 在 9.8 节 中 说 明 它 的 用 法 。 


对 于 epoll 而 言 ， 并 没有 enable 事 件 和 disable 事 件 的 概念 ， 另 外 ， 从 
ngx_epoll_ module_ctx 结 构 体 中 可 以 看 出 ，enable 和 add 接 口 都 是 使 用 
ngx_epoll_add_event 方 法 实现 的 ， 而 disable 和 del 接 口 都 是 使 用 
ngx_epoll_del_event 方 法 实现 的 。 下 面 以 ngx_epoll_add_event 方 法 为 例 


介绍 一 下 它们 是 如 何 调 用 epoll_ct 加 epoll 中 添加 事件 或 从 epoll 中 删除 事 
件 的 。 


static ngx_int_t 
ngx_epoll add event(ngx_ event _t *ev, ngx_int_t event, ngx_uint_t flags) 


int op; 
Uint32_t events, prev,; 
ngx_event_t *e; 
ngx_connection_t ey 


struct epoll event ee; 
// 每 个 事件 的 


data 成 员 都 存放 着 其 对 应 的 


ngx_connection_t 连 接 


ev->data,; 


| 
/* 下 面 会 根据 


event 参 数 确定 当前 事件 是 读 事 件 还 是 写 事件 ， 这 会 决定 
events 是 加 上 

EPOLLIN 标 志 位 还 是 

EPOLLOUT 标 志 位 

x 


events = (uint32_t) event ， 


// 根据 


active 标 志 位 确定 是 否 为 活跃 事件 ， 以 决定 到 底 是 修改 还 是 添加 事件 


if (e->active) { 
op = EPOLL_CTL_MOD; 


} else { 
op = EPOLL_CTL_ADD; 


} 

// 加 入 
flags 参 数 到 
events 标 志 位 中 


ee.events = events | (uint32 _t) flags,; 


/*ptr 成 员 存储 的 是 


ngx_connection_t 连 接 ， 可 参见 


9.6.2 节 中 
epol1 的 使 用 方式 。 在 


9.2 节 中 曾经 提 到 过 事件 的 


instance 标 志 位 ， 下 面 就 配合 


ngx_epoll_process_events 方 法 说 明 它 的 用 法 


*/ 
ee.data.ptr = (void *) ((uintptr_t) c | ev->instance); 
// 调 


epo11_ct1 方 法 向 


epol1 中 添加 事件 或 者 在 


epol11 中 修改 事件 


if (epoll ctl(ep, op, c->fd, &ee) == -1) { 
ngx_1log_error(NGX_LOG ALERT, ev->log, ngx_errno, 
"epoll ctl(%d, %d) failed", op, c->fd); 
return NGX_ERROR,; 


} 
// 将 事件 的 


active 标 志 位 置 为 


EE 一 > 记 和 击 


1， 表 示 当 前 事件 是 活跃 的 


ev->active = 1; 
return NGX_oKk; 


ngx_epoll_del_event 方 法 也 通过 epoll_ctl 删 除 epoll 中 的 事件 ， 具 体 代 
码 这 里 不 再 罗列 ， 读 者 可 参照 hgx_epoll_add_event 的 实现 理解 其 意义 。 


对 于 ngx_epoll_add_connection 方 法 和 ngx_epoll_del_connection 方 
法 ， 也 是 调用 epoll_ctl 方 法 同 epoll 中 添加 事件 或 者 在 epoll 中 删除 事件 
的 ， 只 是 每 一 个 连接 都 对 应 读 / 写 事件 。 因 此 ， 


ngx_epoll_add_connection 方 法 和 ngx_epoll_del_connection 方 法 在 每 次 执 


行 时 也 都 是 同时 将 每 个 连接 对 应 的 谈 、 写 事件 active 标 志 位 置 为 1 的 ， 
这 里 将 不 再 给 出 其 代码 。 


对 于 事件 的 instance 标 志 位 ， 已 经 在 9.2 节 中 简单 地 介绍 了 它 的 意 
义 ， 下 面 将 结合 ngx_epoll_process_events 方 法 具体 说 明 其 意义 。 
ngX_epoll_process_events 是 实现 了 收集 、 分 发 事件 的 process_events 接 口 
的 方法 ， 其 主要 代码 如 下 所 示 。 


static ngx_int_t ngx_epoll process events(ngx_cycle t *cycle, ngx_msec_t timer, 
ngx_uint_t flags) 


{ 
int events; 
Uint32_t revents; 
ngx_int_t instance, i; 
ngx_event_t *rev, *Wwev, **queue,; 
ngx_connection t *c,; 
/* 调 

epoll_wait 获 取 事 件 。 注 意 ， 


timer 参 数 是 在 


process_events 调 用 时 传 入 的 ， 在 


9.7 和 
9.8 节 中 会 提 到 这 个 参数 


4h 
events = epoll wait(ep, event_list, (int) nevents, timer); 


/A 在 


9.7 节 中 会 介绍 


Nginx 对 时 间 的 缓存 和 管理 。 当 


flags 标 志 位 指示 要 更 新 时 间 时 ， 就 是 在 这 里 更 新 的 


4 
If (flags & NGX_UPDATE_TIME || ngx_event_ timer_alarm) { 
// 更 新 时 间 ， 参 见 
9.7.1 节 


ngx_time_update()， 


// 遍历 本 次 


epo11_wait 返 回 的 所 有 事件 


for (i = 0; i < events; I++) { 
/* 对 照 着 上 面 提 到 的 


ngx_epoll_add_event 方 法 ， 可 以 看 到 
ptr 成 员 就 是 


ngx_connection_t 连 接 的 地 址 ， 但 最 后 


1 位 有 特殊 含义 ， 需 要 把 它 屏蔽 掉 


*/ 


c = event list[il].data.ptr; 
// 将 地 址 的 最 后 一 位 取出 来 ， 


instance 变 量 标识 


instance = (uintptr_t) c &1; 
/* 无 论 是 


32 位 还 是 


64 位 机 器 ， 其 地 址 的 最 后 


1 位 肯定 是 


09， 可 以 用 下 面 这 行 语句 把 


ngx_connection_t 的 地 址 还 原 到 真正 的 地 址 值 


*/ 
= (ngx_connection t *) ((uintptr_t) c & (uintptr_t) ~1); 
7/ 取出 恋 事件 
rev = C->read 
// 判断 这 个 读 事件 是 否 为 过 期 事件 
If (c->fd == -1 || rev->instance != instance) { 
/* 当 
fd 套 接 字 描述 符 为 
-1 或 者 


instance 标 志 位 不 相等 时 ， 表 示 这 个 事件 已 经 过 期 了 ， 不 用 处 理 


HB 


*/ 
continue,; 


} 
// 取出 事件 类 型 


revents = event_list[i].events; 


牛 是 活路 的 


ul 
> 


// 如 果 是 读 事件 且 访 3 


if ((revents & EPOLLIN) && rev->active) { 


// flags 参 数 中 含有 


NGX_POST_EVENTS 表 示 这 批 事件 要 延 后 处 理 


if (flags & NGX_POST_EVENTS) { 
/* 如 果 要 在 


post 队 列 中 延 后 处 理 该 事件 ， 首 先 要 判断 它 是 新 连接 事件 还 是 普通 事件 ， 以 决定 把 它 加 入 到 


ngx_posted_accept_events 队 列 或 者 


ngx_posted_events 队 列 中 。 关 于 


post 队 列 中 的 事件 何 时 执行 ， 可 参见 
9.8 节 内 容 
wi 


dueue = (ngx_event _t **) (rev->accept 
&ngx_posted_events); 


// 将 这 个 事件 添加 到 相应 的 延 后 执行 队列 中 


ngx_locked_post_event(rev, queue); 
} else { 
// 立即 调用 读 事件 的 回调 方法 来 处 理 这 个 事件 


rev->handler (rev); 


} 
} 
// 取出 写 事件 


wev = c->write; 
If ((revents & EPOLLOUT) && wev->active) { 
// 判断 这 个 读 事件 是 否 为 过 期 事件 


&ngx_posted_accept_events : 


if (c->fd == -1 || wev->instance != instance) { 


/* 当 


fd 套 接 字 描述 符 为 
-1 或 者 


instance 标 志 位 不 相等 时 ， 表 示 这 个 事件 已 经 过 期 了 ， 不 用 处 理 


continue; 


if (flags & NGX_POST_EVENTS) { 
// 将 这 个 事件 添加 到 


post 队 列 中 延 后 处 理 


ngx_locked_post_event(wev, &ngx_posted events); 
} else { 
// 立即 调用 这 个 写 事件 的 回调 方法 来 处 理 这 个 事件 


wev->handler (wev); 


return NGX_OK; 


ngx_epoll_process_events 方 法 会 收集 当前 触发 的 所 有 事件 ， 对 于 不 
需要 加 入 到 post 队 列 延 后 处 理 的 事件 ， 该 方法 会 立刻 执行 它们 的 回调 方 
法 ， 这 其 实生 在 做 分 发 事件 的 工作 ， 只 是 它 会 在 目 己 的 进程 中 调用 这 
些 回 调 方法 而 已 ， 因 此 ， 每 一 个 回调 方法 都 不 能 导致 进程 休眠 或 者 消 
耗 太 多 的 时 间 ， 以 免 epoll 不 能 即时 地 处 理 其 他 事件 。 


instance 标 志 位 为 什么 可 以 判断 事件 是 否 过 期 ? 从 上 面 的 代码 可 以 
看 出 ，instance 标 志 位 的 使 用 其 实 很 向 单 ， 它 利用 了 指针 的 最 后 一 位 一 
定 是 0 这 一 特性 。 既 然 最 后 一 位 始终 都 是 0， 那 么 不 如 用 来 表示 
instance。 这 样 ， 在 使 用 ngx_epoll_add_event 方 法 同 epoll 中 添加 事件 时 ， 
束 把 epoll_event 中 联合 成 员 data 的 ptr 成 员 指 同 ngx_connection_t 连 接 的 地 
址 ， 同 时 把 最 后 一 位 置 为 这 个 事件 的 instance 标 志 。 而 在 


ngx_epoll_process_events 方 法 中 取出 指 同 连接 的 ptr 地 址 时 ， 先 把 最 后 一 
位 instance 取 出 来 ， 再 把 ptr 还 原 成 正常 的 地 址 赋 给 ngx_connection_t 连 
接 。 这 样 ，instance 究 竟 放 在 何 处 的 问题 也 就 解决 了 。 


那么 ， 过 期 事件 又 是 怎么 回 事 呢 ? 举 个 例子 ， 假 设 epoll_wait 一 次 
返回 3 个 事件 ， 在 第 1 个 事件 的 处 理 过 程 中 ， 由 于 业务 的 需要 ， 所 以 关 
闭 了 一 个 连 返 ， 而 这 个 连接 恰好 对 应 第 3 个 事件 。 这 样 的 话 ， 在 处 理 到 
第 3 个 事件 时 ， 这 个 事件 束 已 经 是 过 期 事件 了 ， 一 旦 处 理 必然 出 错 。 既 
然 如 此 ， 把 天 闭 的 这 个 连接 的 fd 套 接 子 转 为 -1 能 解决 问题 吗 ? 答案 在 不 
能 处 理 所 有 情况 。 


下 面 完 来 看 看 这 种 貌似 不 可 能 发 生 的 场景 到 压 是 怎么 发 生 的 : 假 
设 第 3 个 事件 对 应 的 ngx_connection_t 连 接 中 的 fd 套 接 字 原先 是 50， 处 理 
第 1 个 事件 时 把 这 个 连接 的 套 接 字 关闭 了 ， 同 时 置 为 -1， 并 且 调 用 
ngx_free_connection 将 该 连接 归还 给 连接 池 。 在 
ngX_epoll_process_events 方 法 的 循环 中 开始 处 理 第 2 个 事件 ， 恰 好 第 2 个 
事件 是 建立 新 连接 事件 ， 调 用 ngx_get_connection 从 连接 池 中 取出 的 连 
接 非 常 可 能 殉 是 刚刚 释放 的 第 3 个 事件 对 应 的 连接 。 由 于 套 接 字 50 刚 刚 
被 释放 ，Linux 内 核 非 常 有 可 能 把 刚刚 释放 的 套 接 字 50 又 分 配给 新 建立 
的 连接 。 因 此 ， 在 循环 中 处 理 第 3 个 事件 时 ， 这 个 事件 就 症 过 期 的 了 ! 
它 对 应 的 事件 是 关闭 的 连接 ， 而 不 是 新 建立 的 连接 。 


如 何 解 决 这 个 问题 ? 依靠 instance 标 志 位 。 当 调用 
ngx_get_connection 从 连接 池 中 获取 一 个 新 连接 时 ，instance 标 志 位 就 会 
置 反 ， 代 码 如 下 所 示 。 


ngx_connection 七 * 
ngx_get_connection(ngx_socket_t s, ngx_log_t *1og) 


// 从 连接 池 中 获取 一 个 连接 


ngx_connection t *c,; 
c = ngx_cycle->free_connections,; 


rev 
WeV 


c->read; 
c->write; 


instance = rev->instance; 
// 将 


instance 标 志 位 置 为 原来 的 相反 值 


rev->instance 
wev->instance 


!instance; 
!instance; 


return c; 


这 样 ， 当 这 个 ngx_connection_t 连 接 重 复 使 用 时 ， 它 的 instance 标 志 
位 一 定 是 不 同 的 。 因 此 ， 在 ngx_epoll_process_events 方 法 中 一 旦 判断 
instance 发 生 了 变化 ， 束 认为 这 是 过 期 事件 而 不 予 处 理 。 这 种 设计 方法 
苹 非 党 值得 读者 学 习 的 ， 因 为 它 几 乎 没有 增加 任何 成 本 束 很 好 地 解决 
了 服务 万 开发 时 一 定 会 出 现 的 过 期 事件 问题 。 


目前 ， 在 ngx_event_actions_t 接 口中 ， 所 有 事件 模块 都 没有 实现 
process_changes 方 法 。done 接 口 是 由 ngx_epoll_done 方 法 实现 的 ， 在 
Nginx 退 出 服务 时 它 会 得 到 调用 。ngx_epoll_done 主 要 是 关闭 epoll 描 述 
符 ep， 同 时 释放 event_list 数 组 。 


了 解 了 ngx_epoll_module_ctx 中 所 有 接口 的 实现 后 ， 
ngx_epoll_ module 模 块 的 定义 残 非 党 简单 了 ， 如 下 所 示 。 


ngx_module t ngx_epoll module = { 
NGX_MODULE_V1, 


&ngx_epoll module_ctx, /* module context */ 
ngx_epoll_ commands, /* module directives */ 
NGX_EVENT_MODULE， /* module type */ 

NULL, /* init master */ 

NULL, /* init module */ 

NULL, /* init process */ 
NULL, /* init thread */ 

NULL, /* exit thread */ 

NULL, /* exit process */ 

NULL /* exit master */ 


了 
NGX_MODULE_V1_PADDING 


这 里 不 需要 再 实现 ngx_module_t 接 口中 的 7 个 回调 方法 了 。 


至 此 ， 我 们 完整 地 介绍 了 ngx_epoll_module 模 块 是 如 何 实现 事件 驱 
动机 制 的 内 容 的 。 事 实 上 ， 其 他 事件 驱动 模块 的 实现 与 
ngx_epoll_ module 模 块 的 差别 并 不 是 很 大 ， 读 者 可 以 参照 本 节 内 容 阅读 
其 他 事件 模块 的 源 代码 。 


9.7 ”定时 器 事件 


Nginx 实 现 了 自己 的 定时 器 触发 机 制 ， 它 与 epoll 等 事件 驱动 模块 处 
理 的 网 络 事件 不 同 : 在 网 络 事件 中 ， 网 络 事件 的 触发 是 由 内 核 完 成 
的 ， 内 核 如 果 文 持 epol 丈 可 以 使 用 ngx_epoll_ module 模 块 驱动 事件 ， 内 
核 如 果 仅 支持 select 那 就 得 使 用 ngx_select_module 模 块 驱动 事件 ， 定 时 
妖 事 件 则 完全 是 由 Nginx 自 身 实 现 的 ， 它 与 内 核 完 全 无 天 。 那 么 ， 所 有 
事件 的 定时 器 是 如 何 组 织 起 来 的 呢 ? 在 事件 超时 后 ， 定 时 器 是 如 何 触 
发 事件 的 呢 ? 读者 将 在 9.7.2 市 中 看 到 定时 器 事件 的 设计 ， 但 首先 需要 
弄 清 楚 Nginx 的 时 间 是 如 何 管理 的 。Nginx 与 一 般 的 服务 器 不 同 ， 出 于 
性 能 的 考虑 (不 需要 每 次 获取 时 间 都 调用 gettimeofday 方 法 ) ，Nginx 使 
用 的 时 间 是 缓存 在 其 内 存 中 的 ， 这 样 ， 在 Nginx 模 块 获 取 时 间 时 ， 只 是 
获取 内 存 中 的 几 个 整 型 变量 而 已 。 这 个 缓存 的 时 间 是 如 何 更 新 的 呢 ? 
又 是 在 什么 时 刻 更 新 的 呢 ? 这 些 问 题 读者 会 在 9.7.1 世 中 获得 答案 。 


9.7.1 缓存 时 间 的 管理 


Nginx 中 的 每 个 进程 都 会 单独 地 管理 当前 时 间 ， 下 面 来 看 一 下 缓存 
的 全 局 时 间 变 量 是 什么 。ngx_time t 结 构 体 是 缓存 时 间 变 量 的 类 型 ， 如 
不 所 大 


typedef struct { 
// 格林 威 治 时 间 


1970 年 


工 月 


0 分 
0 秒 到 当前 时 间 的 秒 数 


[es 


time_t sec,; 
// sec 成 员 只 能 精确 到 秒 ， 


msec 则 是 当前 时 间 相 对 于 


sec 的 训 秒 偏 移 量 


ngx_uint_t msec 
// 时 区 


ngx_int_t gmtoff， 
} ngx_time_t; 


可 以 看 到 ，ngx_time_t 是 精确 到 毫秒 的 。 当 然 ，ngx_time_t 结 构 用 
起 来 并 不 是 那 么 方便 ， 作 为 Web 上 服务 右 ， 很 多 时 候 要 用 到 可 读 性 较 强 的 
规范 的 时 间 字 符 串 ， 因 此 ，Nginx 定 义 了 以 下 全 局 变量 用 于 缓存 时 间 ， 
代码 如 下 。 


// 格林 威 治 时 间 


1970 年 


1 


0 分 
9 秒 到 当前 时 间 的 毫秒 数 


en 


volatile ngx_msec_t ngx_current_msec ' 
// ngx_time_t 结 构 体形 式 的 当前 时 间 


volatile ngx_time t *ngx_cached time; 
/* 用 于 记录 


Lh 


error_10g 的 当前 时 间 字 符 串 ， 它 的 格式 类 似 ]] 
"1970/09/28 12:00:00"*/ 

volatile ngx_str_t ngx_cached err_log time; 
/* 用 于 


HTTP 相 关 的 当前 时 间 字 符 串 ， 它 的 格式 类 似 了 


I 


"Mon, 28 Sep 1970 06:00:00 GMT"*/ 
volatile ngx_str_t ngx_cached_http_time,; 


/* 用 于 记录 


HTTP 日 志 的 当前 时 间 字 符 串 ， 它 的 格式 类 似 


"28/Sep/1970:12:00:00 +0600"*/ 
volatile ngx_str_t ngx_cached http_log time,; 
// 以 


ISO 8691 标 准 格式 记录 下 的 字符 串 形式 的 当前 时 间 


volatile ngx_str_t ngx_cached http_log iso8601.; 


Nginx 为 用 户 提供 了 6 种 当前 时 间 的 表示 形式 ， 这 已 经 足够 用 了 。 
Nginx 绥 存 时 间 的 操作 方法 见 表 9-4 所 示 。 


表 9-4 ”Nginx 绥 存 时 间 的 操作 方法 


时 间 方 法 名 


void ngx_time _init(void); 


void ngx_time_update(void) 


u_char *ngx_http_time 
(u_char *buf time ttb) 


u char *ngx_http_cookie 
time(u_char *buf time tt 


void ngx gmtime 
(time tt, ngx_ tm t *tp) 


时 间 方 法 名 


time tngx next time 
(time t when) 


#define ngx_time() 
ngx cached time->sec 


#define ngx_timeofday() 


(ngx time t*)ngx cached time 


执行 意义 

初始 化 当前 进程 中 缓存 的 时 间 变 量 ， 同 
时 会 第 一 次 根据 gettimeofday 调用 刷新 组 
存 时 间 


使 用 gettimeofday 调用 以 系统 时 间 更 新 
缓存 的 时 间 ， 上 述 的 ngx_current_ msec、 
无 ngx _ cached time, ngx cached err log 
time、 ngx cached http time、 ngx_ cached_ 
http_log time、 ngx cached http log_ 
iso8601 这 6 个 全 局 变量 都 会 得 到 更 新 


t 是 需要 转换 的 时 间 ， 它 是 格 
林 威 治 时 间 1970 年 1 月 1 日 凌晨 | 将 时 间 t 转 换 成 “Mon, 28 Sep 1970 06:00:00 
0 点 0 分 0 秒 到 某 一 时 间 的 秒 数 , |GMT” 形 式 的 时 间 ， 返 回 值 与 buf 是 相同 
buf 是 t 时 间 转 换 成 字符 串 形 式 的 | 的 ， 都 是 指向 存放 时 间 的 字符 串 
HTTP 时 间 后 用 来 存放 字符 串 的 内 存 

t 是 需要 转换 的 时 间 ， 它 是 格 
林 威 治 时 间 1970 年 1 月 1 日 凌晨 | 将 时 间 t 转 换 成 “Mon,28-Sep-70 06:00:00 
0 点 0 分 0 秒 到 某 一 时 间 的 秒 数 , |GMT” 形 式 适 用 于 cookie 的 时 间 ， 返 回 值 
buf 是 t 时 间 转 换 成 字符 串 形式 适 | 与 buf 是 相同 的 ， 都 是 指向 存放 时 间 的 字 
用 于 cookie 的 时 间 后 用 来 存放 字 | 符 串 
符 串 的 内 存 

t 是 需要 转换 的 时 间 ， 它 是 格林 
威 治 时 间 1970 年 1 月 1 日 凌晨 0 
点 0 分 0 秒 到 某 一 时 间 的 秒 数 ，tp 
是 ngx_tm t 类 型 的 时 间 ， 实 际 上 
就 是 标准 的 tm 类 型 时 间 


将 时 间 t 转 换 成 ngx tm t 类 型 的 时 间 。 
下 面 会 说 明 ngx_tm t 类 型 


\ 
~ 


执行 意义 

返回 -1 表示 失败 ， 和 否则 会 返回 : 中 如果 
when 表示 当天 时 间 秒 数 ， 当 它 合并 到 实际 
时 间 后 , 已 经 超过 当前 时 间 ， 那 么 就 返回 
when 合并 到 实际 时 间 后 的 秒 数 (相对 于 格 
when 表示 期 待 过 期 的 时 间 ， 它 | 林 威 治 时 间 1970 年 1 月 1 日 凌晨 0 点 0 分 
0 秒 到 某 一 时 间 的 秒 数 ); 

@@ 反 之 ， 如 果 合 并 后 的 时 间 早 于 当前 时 
间 ， 则 返回 下 一 天 的 同一 时 刻 (当天 时 刻 ) 
的 时 间 。 它 日 前 仅 具 有 与 expires 配置 项 相 
关 的 缓存 过 期 功能 


无 获取 到 格林 威 治 时 间 1970 年 1 月 1 日 凌 
晨 0 点 0 分 0 秒 到 当前 时 间 的 秒 数 


仅 表 示 一 天 内 的 秒 数 


ngx_tm_t 是 标准 的 tm 类 型 时 间 ， 


的 ， 代 码 如 下 。 


struct tm { 


// 秒 


- 取 值 区 间 为 


[9,59] 


int tm_sec 
/7 分 


- 取 值 区 间 为 


[0, 59] 


int tm_min; 
// 时 


- 取 值 区 间 为 
[90, 23] 
int tm_hour,; 
// 一 个 月 中 的 日 期 
- 取 值 区 间 为 
[1, 31] 
int tm_mday 
// 月 份 (从 始 ， 
9 代表 一 月 ) 
- 取 值 区 间 为 
[9, 11] 
int tm_mon; 
// 年 份 ， 其 值 等 于 实际 各 
1900 
int tm_year 
// 星期 
- 取 值 区 间 为 


[9,6]， 其 中 


1 代表 星期 一 ， 依 此 类 推 


星期 天 ， 


int tm_wday; 
/* 从 每 年 的 


始 的 天 数 


FE 份 减 去 


下 面 完 看 一 下 tm 时 间 是 什么 样 


- 取 值 区 间 为 


[9,365]， 其 中 


6 代表 


二 月 


2 日 ， 依 此 类 推 


*/ 
int tm_yday; 
/* 夏 令 时 标识 符 。 在 实行 夏令 时 的 时 候 ， 


tm_isdst 为 正 ， 不 实行 夏令 时 的 时 候 ， 


tm_isdst 为 

9; 在 不 了 解 情况 时 ， 
tm_isdst 为 负 

4 


int tm isdst,; 


}; 


ngx_tm_t 与 tm 用 法 是 完全 一 致 的 ， 如 下 所 示 。 


typedef struct tm ngx_tm_t; 
#define ngx_tm_ sec tm_sec 
#define ngx_tm min tm_min 
#define ngx_tm_hour tm_hour 
#define ngx_tm mday tm_mday 
#define ngx_tm mon tm_mon 
#define ngx_tm_ year tm_year 
#define ngx_tm wday tm_wday 
#define ngx_tm_isdst tm_isdst 


可 以 看 到 ，ngx_tm_t 中 类 似 ngx_tm_sec 这 样 的 成 员 与 tm_sec 是 完全 
一 致 的 。 


这 个 缓存 时 间 什 么 时 候 会 更 新 昵 ? 对 于 worker 进 程 而 言 ， 除 了 
Nginx 局 动 时 更 新 一 次 时 间 外 ， 任 何 更 新 时 间 的 操作 都 只 能 由 
ngx_epoll_process_events 方 法 (参见 9.6.3 市 ) 执行 。 回 顾 一 下 
ngx_epoll_process_events 方 法 的 代码 ， 当 flags 参 数 中 有 
NGX_UPDATE_TIME 标 志 位 ， 或 者 ngx_event_timer_alarm 标 志 位 为 1 
H 上 时 ， 束 会 调用 ngx_time_update 方 法 更 新 缓存 时 间 。 


9.7.2 ”缓存 时 间 的 精度 


上 文 简单 地 介绍 过 缓存 时 间 的 更 新 策略 ， 它 是 与 
ngx_epoll_process_events 方 法 的 调用 频率 及 其 flag 参 数 相 关 的 。 实 际 
上 ，Nginx 还 提供 了 设置 更 新 缓存 时 间 频 率 的 功能 〈 也 束 是 至 少 每 隔 
timer_resolution 芝 秒 必须 更 新 一 次 缓存 时 间 ) ， 通 过 在 nginx.conf 文 件 
中 的 timer_resolution 配 置 项 可 以 设置 更 新 的 最 小 频率 ， 这 样 束 保 证 了 绥 
存 时 间 的 精度 。 


dS 


下 面 看 一 下 timer_resolution 是 如 何 起 作用 的 。 在 图 9-4 的 第 5 步 中 ， 
ngx_event_core_module 模 块 初始 化 时 会 使 用 setitimer 系 统 调 用 告诉 内 核 
隔 timer_resolution 军 秒 调用 一 次 ngx_timer_signal_handler 方 法 。 而 
ngx_timer_signal_handler 方 法 则 会 将 ngx_event_timer_alarm 标 志 位 设 为 
1， 这 样 一 来 ,一旦 调用 ngx_epoll_process_events 方 法 ， 如 果 间 隔 的 时 


间 超 过 timer_resolution 宣 秒 ， 肯 定 会 更 新 缓存 时 间 。 


但 如 果 很 久 都 不 调用 ngx_epoll_process_events 方 法 呢 ? 例如 ， 远 超 
过 timer_resolution 毫 秒 的 时 间 内 ngx_epoll_process_events 方 法 都 得 不 到 
调用 ， 那 时 间 精 度 如 何 保证 呢 ? 在 这 种 情况 下 ，Nginx 只 能 从 事件 模块 
对 ngx_event_actions 中 process_events 接 口 的 实现 来 保证 时 间 精 度 了 。 
process_events 方 法 的 第 2 个 参数 timer 表 示 收 集 事 件 时 的 最 长 等 待 时 间 。 
例如 ， 在 epoll 模 块 下， 这 个 timer 束 十 epoll_wait 调 用 时 传 入 的 超时 时 间 
参数 。 如 果 在 设置 了 timer_resolution 后 ， 这 个 timer 人 参数 就 是 -1， 它 表示 
如 采 epoll_wait 等 调用 检测 不 到 已 经 发 生 的 事件 ， 将 不 等 竺 而 是 立刻 返 
回 ， 这 样 就 控制 了 时 间 精 度 。 当 然 ， 如 果 某 个 事件 消费 模块 的 回调 方 
法 执行 时 占用 的 时 间 过 长 ， 时 间 精 度 还 是 难以 得 到 保证 的 。 


9.7.3 ”定时 器 的 实现 


定时 絮 是 通过 一 棵 红 黑 树 实现 的 。ngx_event_timer_rbtree 就 是 所 有 
定时 姻 事 件 组 成 的 红 墨 树 ， 而 ngx_event_timer_sentinel] 就 是 这 棵 红 墨 树 
的 哨兵 太 点 ， 如 下 所 示 。 


ngx_thread volatile ngx_rbtree t ngx_event timer_rbtree; 
static ngx_rbtree node t ngx_event_ timer_sentinel,; 


这 棵 红 黑 树 中 的 每 个 节点 都 是 ngx_event_t 事 件 中 的 timer 成 员 ， 而 
ngx_rbtree_node_t 闻 点 的 天 键 字 就 是 事件 的 超时 时 间 ， 以 这 个 超时 时 间 
的 大 小 组 成 了 二 又 排序 树 ngx_event_timer_rbtree。 这 样 ， 如 果 需 要 找 出 


最 有 可 能 超时 的 事件 ， 那 么 将 ngx_event_timer_rbtree 树 中 最 左边 的 节点 
取出 来 即 可 。 只 要 用 当前 时 间 去 比较 这 个 最 左边 市 点 的 超时 时 间 ， 整 
会 知道 这 个 事件 有 没有 触发 超时 ， 如 采 还 没有 触发 超时 ， 那 么 会 知道 
最 少 还 要 经 过 多 少 翅 秒 满足 超时 条 件 而 触发 超时 。 先 看 一 下 定时 袁 的 
操作 方法 ， 见 表 9-5 。 


表 9-5 定时 做 的 操作 方法 
方法 名 执行 意义 


ngx int tngx_event timer init log 是 可 以 记录 日 志 的 ngx a 
和 -| 初始 化 定时 器 


(ngx log t*#log): log t 对 象 
找 出 红 黑 树 中 最 左边 的 节点 ， 如 果 它 的 超 
时 时 间 大 于 当前 时 间 ， 也 就 表明 目前 的 定时 
器 中 没有 一 个 事件 满足 触发 条 件 ， 这 时 返回 
无 这 个 超时 与 当前 时 间 的 差 值 ， 也 就 是 需要 经 
过 多 少 毫 秒 会 有 事件 超时 触发 ;如果 它 的 超 
时 时 间 小 于 或 等 于 当前 时 间 ， 则 返回 0， 表 
示 定 时 器 中 已 经 存在 超时 需要 触发 的 事件 
检查 定时 器 中 的 所 有 事件 ， 按 照 红 黑 树 关 
无 键 字 由 小 到 大 的 顺序 依次 调用 已 经 满足 超时 
条 件 需要 被 触发 事件 的 handler 回调 方法 


ngx msec tngx event find 


timer(void): 


void ngx_ event explre_ 


timers(vo1d): 


static ngx_inline void 
ngx event del timer ev 是 需要 操作 的 事件 从 定时 咒 中 移 除 一 个 事件 


(ngx_ event t *ev) 


ev 是 需要 操作 的 事件 ,timer 
的 单位 是 毫秒 ， 它 告诉 定时 器 事 | 添加 一 个 定时 咒 事 件 ， 超 时 时 间 为 timer 
件 ev 希望 timer 毫秒 后 超时 ， 同 | 毫秒 
时 需要 回调 ev 的 handler 方法 


static ngx_inline void 
ngx event add timer(ngx_ 
event t *ev, ngx msec ttimer) 


事实 上 ， 还 有 两 个 宏 与 ngx_event_add_timer 方 法 和 
ngx_event_del_timer 方 法 的 用 法 是 完全 一 样 的 ， 如 下 所 示 。 


#define ngx_add timer ngx_event_ add timer 
#define ngx_del timer ngx_event _ del timer 


从 表 9-5 可 以 看 出 ， 只 要 调用 ngx_event_expire_timers 方 法 就 可 以 触 
发 所 有 超时 的 事件 ， 在 这 个 方法 中 ， 循 环 调用 所 有 满足 超时 条 件 的 事 
件 的 handler 回 调 方法 。 那 么 ， 多 人 久 调 用 一 次 ngx_event_expire _timers 方 
法 呢 ? 这 个 时 间 频 率 可 以 部 分 参照 ngx_event_find_timer 方 法 ， 因 为 
ngx_event_find_timer 会 告诉 用 户 下 一 个 最 近 的 超时 事件 多 久 后 会 发 
和 后。 


在 9.8.5 世 中 ， 读 者 会 看 到 ngx_event_expire_timers 究 竟 什 么 时 候 会 
被 调用 。 


9.8 ”事件 续 动 框 染 的 处 理 流程 


本 世 开 始 讨论 事件 处 理 流 程 。 在 9.5.1F 中 已 经 看 到 ， 图 9-4 的 第 12 
步 会 将 监听 连接 的 读 事 件 设 为 ngx_event_accept 方 法 ， 在 第 13 步 会 把 监 
听 连 接 的 读 事件 添加 到 ngx_epoll module 事 件 驱 动 模块 中 。 这 样 ， 在 执 
行 ngx_epoll_process_events 方 法 时 ， 如 果 有 新 连接 事件 出 现 ， 则 会 调用 
ngx_event_accept 方 法 来 建立 新 连接 。 在 9.8.1 节 中 将 会 讨论 
ngx_event_accept 方 法 的 执行 流程 。 


当然 ， 建 立 连接 其 实 没 有 那么 简单 。Nginx 出 于 充分 发 挥 多 核 CPU 
架构 性 能 的 考虑 ， 使 用 了 多 个 worker 子 进程 监听 相同 端口 的 设计 ， 这 样 
多 个 子 进程 在 accept 建 立新 连接 时 会 有 争 抢 ， 这 会 市 来 著名 的 “ 惊 群 > 问 
题 ， 子 进程 数量 越 多 问题 越 明 显 ， 这 会 造成 系统 性 能 下 降 。 在 9.8.2 下 
中 ， 我 们 会 讲 到 在 建立 新 连接 时 Nginx 是 如 何 避 免 出 现 “ 惊 群 * 现 象 的 。 


男 外 ， 建 立 连接 时 还 会 涉及 负载 均衡 问题 。 在 多 个 子 进程 争 抢 处 
理 一 个 新 连接 事件 时 ， 一 定 只 有 一 个 worker 子 进程 最 终 会 成 功 建立 连 
接 ， 随 后 ， 它 会 一 直 处 理 这 个 连接 直到 连接 关闭 。 那 么 ， 如 果 有 的 子 
进程 很 “勤奋 ”"， 它 们 抢 着 建立 并 处 理 了 大 部 分 连接 ， 而 有 的 子 进程 

则 “运气 不 好 ”， 只 处 理 了 少量 连 授 ， 这 对 多 核 CPU 架 构 下 的 应 用 是 很 不 
利 的 ， 因 为 子 进程 间 应 该 是 乎 等 的 ， 每 个 子 进程 应 该 尽量 地 独占 一 个 


CPU 核心 。 子 进程 间 负 载 不 均衡 ， 必 然 影响 整个 服务 的 性 能 。 在 9.8.3 
万 中 ， 我 们 会 看 到 Nginx 征 如 何 解决 负载 均衡 问题 的 。 


实际 上 上， 上述 问题 的 解决 离 不 开 Nginx 的 post 事 件 处 理 机 制 。 这 个 
post 事 件 是 什么 意思 呢 ? 它 表 示人 允许 事件 延 后 执行 。Nginx 设 计 了 两 个 
post 队 列 ， 一 个 是 由 被 触发 的 监听 连接 的 读 事件 构成 的 
ngx_posted_accept_events 队 列 ， 男 一 个 是 由 普通 读 / 写 事件 构成 的 
ngx_posted_events 队 列 。 这 样 的 post 事 件 可 以 让 用 户 完 成 什么 样 的 功能 
呢 ? 


-将 epoll_wait 产 生 的 一 批 事件 ， 分 到 这 两 个 队列 中 ， 让 存放 着 新 连 
接 事 件 的 ngx_posted_accept_events 队 列 优先 执行 ， 存 放 普 通 事件 的 
ngx_posted_events 队 列 最 后 执行 ， 这 是 解决 “ 惊 群 " 和 人 负载 均衡 两 个 问题 
的 关键 。 


.如 果 在 处 理 一 个 事件 的 过 程 中 产生 了 另 一 个 事件 ， 而 我 们 希望 这 
个 事件 随后 执行 (不 是 立刻 执行 ， 就 可 以 把 它 放 到 post 队 列 中 。 在 
9.8.3 节 中 会 介绍 post 队 列 。 


我 们 在 9.8.5 节 中 将 本 章 的 网 络 事件 、 定 时 器 事件 进行 综合 考虑 ， 
以 说 明 ngx_process_events_and_timers 事 件 框架 执行 流程 是 如 何 把 连接 
的 建立 、 事 件 的 执行 结合 在 一 起 的 。 


9.8.1 如 何 建立 新 连接 


上 文 提 到 过 ， 处 理 新 连接 事件 的 回调 函数 是 ngx_event_accept， 其 
原型 如 下 。 


void ngx_event_accept(ngx_event_t *ev) 
下 面 简单 介绍 一 下 它 的 流程 ， 如 图 9-6 所 示 。 
下 面 对 流 程 中 的 7 个 步骤 进行 说 明 。 


1) 首先 调用 accept 方 法 试图 建立 新 连接 ， 如 果 没 有 准备 好 的 新 连 
接 事 件 ，ngx_event_accept 方 法 会 直接 返回 。 


2) 设置 负载 均衡 靖 值 ngx_accept_disabled， 这 个 靖 值 是 进程 允许 的 
连接 数 的 1/8 减 去 空 用 连接 数 ， 它 的 具体 用 法 参见 9.8.3 节 。 


1 ) 调 用 accep 访 法 建立 新 的 
TCP 连 接 


[成 功 建立 TCP 连 接 ] 


2) 设 置 负载 均衡 国人 值 


ngx_accept_disabled 


3) 由 连接 池 中 获取 一 个 


ngx_connection {结构 体 


4) 为 这 个 连接 
创建 内 存 池 


5 设置 新 过 扫 大 接合 
的 属性 
:的 污 事 件 深 加 硬 
民风 沁 素 件 深 加 到 


[available 标志 位 为 1] 


[没有 新 连接 可 建立 ] 


6) 将 这 个 新 连 
epoll 中 监 


7) 调 用 监听 端口 上 ngx listening + 结构 体 的 
handler 方 法 处 理 新 连接 


[检查 监听 连接 读 事 件 


的 available 标 志 位 ] 


available 为 0] 


图 9-6 ngx_event_accept 方 法 建立 新 连接 的 流程 


3) 调用 ngx_get_connection 方 法 由 连接 池 中 获取 一 个 
ngx_connection_t 连 接 对 象 。 


4) 为 ngx_connection_t 中 的 pool 指 针 建 立 内 存 池 。 在 这 个 连接 释放 
到 空 内 连接 池 时 ， 释 放 pool 内 存 池 。 
5) 设置 套 接 字 的 属性 ， 如 设 为 非 阻塞 套 接 字 。 


6) 将 这 个 新 连接 对 应 的 读 事 件 添加 到 epoll 等 事件 驱动 模块 中 ， 这 
样 ， 在 这 个 连接 上 如 果 接 收 到 用 户 请 求 epoll_wait， 束 会 收集 到 这 个 事 


7) 调用 监听 对 象 ngx_listening_t 中 的 handler 回 调 方 法 。 
ngx_listening_t 结 构 体 的 handler 回 调 方法 就 是 当 新 的 TCP 连 接 刚 刚 建立 
完成 时 在 这 里 调用 的 。 


最 后 ， 如 采 监 听 事 件 的 available 标 志 位 为 1， 再 次 循环 到 第 1 步 ， 否 
则 ngx_event_accept 方 法 结束 。 事 件 的 available 标 志 位 对 应 着 
multi_accept 配 置 项 。 当 available 为 1 时 ， 告 诉 Nginx 一 次 性 尽量 多 地 建立 
新 连接 ， 它 的 实现 原理 也 就 在 这 里 。 


9.8.2 ”如 何 解 决 “ 惊 群 * 问 题 


只 有 打开 了 accept_mnutex 锁 ， 才 可 以 解决 “ 惊 群 > 问题 。 何 请 “ 惊 
群 ”? 束 像 上 面 说 过 的 那样 ，master 进 程 开 始 监 昕 Web 闹 口 ，fork 出 多 个 
worker 子 进程 ， 这 些 子 进程 开始 同时 监听 同一 个 Web 端 口 。 一 般 情 况 
下 ， 有 多 少 CPU 核 心 ， 就 会 配置 多 少 个 worker 子 进程 ， 这 样 所 有 的 
worker 子 进程 都 在 承担 着 Web 服 务 器 的 角色 。 在 这 种 情况 下 ， 束 可 以 利 
用 每 一 个 CPU 核心 可 以 并 发 工作 的 特性 ， 充 分 发 挥 多 核 机 器 的 “威力 ”。 
但 下 面 假定 这 样 一 个 场景 : 没有 用 户 连 入 服务 第， 某 一 时 刻 恰好 所 有 
的 worker 子 进程 都 休眠 且 等 待 新 连接 的 系统 调用 (如 epoll_wait) ， 这 
时 有 一 个 用 户 向 服务 句 发 起 了 连接 ， 内 核 在 收 到 TCP 的 SYN 包 时 ， 会 激 
活 所 有 的 休眠 worker 子 进程 ， 当 然 ， 此 时 只 有 最 先 开始 执行 accept 的 子 
进程 可 以 成 功 建立 新 连接 ， 而 其 他 worker 子 进程 都 会 accept 失 败 。 这 些 
accept 失 败 的 子 进程 被 内 核 唤醒 是 不 必要 的 ， 它 们 被 唤醒 后 的 执行 很 可 
能 也 是 多 余 的 ， 那 么 这 一 时 刻 它们 占用 了 本 不 需要 占用 的 系统 资源 ， 
引发 了 不 必要 的 进程 上 下 文 切换 ， 增 加 了 系统 开销 。 


也 许 很 多 操作 系统 的 最 新 版 本 的 内 核 已 经 在 事件 驱动 机 制 中 解决 
了 “ 尺 群 ”问题 ， 但 Nginx 作 为 可 移植 性 极 高 的 Web 服 务 器 ， 还 是 在 目 身 
的 应 用 层面 上 较 好 地 解决 了 这 一 问题 。 既 然 “ 恢 群 " 是 多 个 子 进程 在 同 
一 时 刻 监 听 同 一 个 问 口 引起 的 ， 那 么 Nginx 的 解决 方式 也 很 简单 ， 它 规 
定 了 同一 时 刻 只 能 有 唯一 一 个 worker 子 进程 监听 Web 端 口 ， 这 样 就 不 会 
发 生 “ 慰 群 "* 了 ， 此 时 新 连接 事件 只 能 唤醒 唯一 正在 监 昕 端口 的 worker 了 于 
进程 。 


可 是 如 何 限制 在 某 一 时 刻 仅 能 有 一 个 子 进程 监听 Web 喘 口 呢 ?下 面 
看 一 下 ngx_trylock_accept_mnutex 方 法 的 实现 。 在 打开 accept_mnutex 锁 的 
情况 下 ， 只 有 调用 ngx_trylock_accept_mnutex 方 法 后 ， 当 前 的 worker 进 程 
才 会 去 试 着 监听 web 端 口 ， 具 体 实 现 如 下 所 示 。 


ngx_int_t ngx_trylock_accept_mutex(ngx_cycle_t *cycle) 


{ 


/* 使 用 进程 间 的 同步 锁 ， 试 图 获取 


accept_mutex 锁 。 注 意 ， 


ngx_shmtx_try1Lock 返 巨 


示 成 功 拿 到 锁 ， 返 
这 


| 


1 


i 


0 表示 获取 锁 失败 。 这 个 获取 锁 的 过 程 是 非 阻塞 的 ， 此 时 一 旦 锁 被 其 他 


worker 子 进程 占 


ngx_shmtx_trylock 方 法 会 立刻 返回 ( 详 


| 


14 .8 节 ) 


6 
If (ngx_shmtx_trylock(&ngx_accept_ mutex)) { 
/* 如 果 获 取 到 


accept_mutex 锁 ， 但 


ngx_accept_mutex_he1d 为 


1， 则 立刻 返回 。 


眶 
[ 款 


ngx_accept_mutex_held 是 一 个 标志 位 ， 当 


1 时 ， 表 示 当 前 进程 已 经 获取 到 锁 J 


4 
If (ngx_accept_ mutex_held 
&& ngx_accept_events == 0 
&& !(ngx_event_flags & NGX_USE_RTSIG_EVENT ) ) 


| 


// ngx_accept_mutex 锁 之 前 已 经 获取 到 了 ， 立 刻 返 


return NGX_OK; 


} 
// 将 所 有 监听 连接 的 读 事件 添加 到 当前 的 


epol1 等 事件 驱动 模块 中 


If (ngx_enable accept_events(cycle) == NGX_ERROR) { 


驱动 模块 失败 ， 就 必须 释放 


全 


/* 既 然 将 监听 句柄 添加 到 事 们 
ngx_accept_mutex 锁 
SA 


ngx_shmtx_unlock(&ngx_accept_mutex); 
return NGX_ERROR; 


ngx_enable_accept_events 方 法 的 调用 ， 当 前 进程 的 事件 驱动 模块 已 经 开始 监听 所 有 的 端口 ， 这 时 需要 把 


ngx_accept_mutex_held 标 志 位 置 为 


1， 方 便 本 进程 的 其 他 模块 了 解 它 目前 已 经 获取 到 了 锁 


2 
ngx_accept_events = 0; 
ngx_accept_mutex_held = 1; 
return NGX_OK， 
} 
/* 如 果 


ngx_shmtx_trylock 返 下 


ss 


0， 则 表明 获取 


ngx_accept_mutex 锁 失败 ， 这 时 如 果 


ngx_accept_mutex_held 标 志 位 还 为 


1， 即 当前 进程 还 在 获取 到 锁 的 状态 ， 这 当然 是 不 正确 的 ， 需 要 处 理 


*/ 
If (ngx_accept_ mutex_ held) { 
/*ngx_disable_accept_events 会 将 所 有 监听 连接 的 读 事件 从 事 伯 


WT 


驱动 模块 中 移 除 


4 
If (ngx_disable accept_ events(cycle) == NGX _ ERROR) { 
return NGX_ERROR; 


} 
/在 没有 获取 到 


ngx_accept_mutex 锁 时 ， 必 须 把 


ngx_accept_mutex_he1d 置 为 


oO*/ 
ngx_accept_mutex_held = 0; 


return NGX_OK; 


在 上 面 关 于 ngx_trylock_accept_mutex 方 法 的 源 代 码 中 ， 
ngx_accept_mutex 实 际 上 是 Nginx 进 程 间 的 同步 锁 。 第 14 章 我 们 会 详细 


介绍 进程 间 的 同步 方式 ， 目 前 只 需要 清楚 ngx_shmtx_trylock 方 法 是 一 个 
非 阻 塞 的 获取 锁 的 方法 即 可 。 如 果 成 功 获取 到 锁 ， 则 返回 1， 否 则 返回 
0。ngx_shmtx_unlock 方 法 负责 释放 锁 。ngx_accept_mutex_held 是 当前 
进程 的 一 个 全 局 变量 ， 如 果 为 1， 则 表示 这 个 进程 已 经 获取 到 了 
ngx_accept_mutex 锁 ;如果 为 0， 则 表示 没有 获取 到 锁 ， 这 个 标志 位 主 
要 用 于 进程 内 各 模块 了 解 是 否 获 取 到 了 ngx_accept_mutex 锁 ， 具 体 定 义 
如 下 所 示 。 


ngx_shmtx_t ngx_accept_mutex; 
ngx_uint_t ngx_accept_mutex_held; 


此 ， 在 调用 ngx_trylock_accept_mnutex 方 法 后 ， 要 么 是 唯一 获取 到 
ngx_accept_mutex 锁 上 且 其 epoll 等 事件 驱动 模块 开始 监控 Web 咒 口上 的 新 
连接 事件 ， 要 么 是 没有 获取 到 锁 ， 当 前 进程 不 会 收 到 新 连接 事件 。 


如 果 ngx_trylock_accept_mnutex 方 法 没有 获取 到 锁 ， 接 下 来 调用 事件 
驱动 模块 的 process_events 方 法 时 只 能 处 理 已 有 的 连 授 上 的 事件 ， 如 果 
获取 到 了 锁 ， 调 用 process_events 方 法 时 就 会 既 处 理 已 有 连接 上 的 事 
件 ， 也 处 理 新 连接 的 事件 。 这 样 的 话 ， 问 题 义 来 了 ， 什 么 时 候 释 放 
ngx_accept_mutex 锁 呢 ? 等 到 这 批 事件 全 部 执行 完 吗 ? 这 当然 是 不 可 取 
的 ， 因 为 这 个 worker 进 程 上 可 能 有 许多 活跃 的 连接 ， 处 理 这 些 连 接 上 的 
事件 会 占用 很 长 时 间 ， 也 就 是 说 ， 会 有 很 长 时 间 都 没有 释放 


ngx_accept_mutex 锁 ， 这 样 ， 其 他 worker 进 程 就 很 难得 到 处 理 新 连接 的 
机 会 。 


如 何 解 决 长 时 间 占 用 ngx_accept_mutex 锁 的 问题 呢 ? 这 就 要 依靠 
ngX_posted_accept_events 队 列 和 ngx_posted_events 队 列 了 。 首 先 看 下 面 
这 段 代码 : 


If (ngx_trylock_accept_mutex(cycle) == NGX_ERROR) { 
return; 


} 
If (ngx_accept_mutex_held) { 
flags |= NGX_POST_EVENTS; 


调用 ngx_trylock_accept_mutex 斌 图 处 理 监听 端口 的 新 连接 事件 ， 如 
果 ngx_accept_mutex_held 为 1， 束 表示 开始 处 理 新 连接 事件 了 ， 这 时 将 
flags 标 志 位 加 上 NGX_POST_EVENTS。 这 里 的 flags 是 在 9.6.3 节 中 列举 
的 ngx_epoll_process_events 方 法 中 的 第 3 个 参数 flags。 回 顾 一 下 这 个 方 
法 中 的 代码 ， 当 flags 标 志 位 包含 NGX_POST_EVENTS 时 是 不 会 立刻 调 
用 事件 的 handler 回 调 方法 的 ， 代 码 如 下 所 示 。 


If ((revents & EPOLLIN) && rev->active) { 
if (flags & NGX_POST_EVENTS) { 
dueue = (ngx_event _t **) (rev->accept &ngx_posted accept_events : 
&ngx_posted_events ) ， 
ngx_locked_post_event(rev, queue); 
} else { 
rev->handler (rev); 


对 于 写 事件 ， 也 可 以 采用 同样 的 处 理 方法 。 实 际 上 ， 
ngX_posted_accept_events 队 列 和 ngx_posted_events 队 列 把 这 批 事件 归 类 
了 ， 即 新 连接 事件 全 部 放 到 ngx_posted_accept_events 队 列 中 ， 普 通 事 件 
则 放 到 ngx_posted_events 队 列 中 。 这 样 ， 搂 下 来 会 先 处 理 
ngx_posted_accept_events 队 列 中 的 事件 ， 处 理 完 后 就 要 立刻 释放 
ngX_accept_mnutex 锁 ， 接 着 再 处 理 ngx_posted_events 队 列 中 的 事件 ( 参 
见 图 9-7) ， 这 样 就 大 大 减少 了 ngx_accept_mutex 锁 占用 的 时 间 。 


9.8.3 ”如 何 实现 负载 均衡 


与 “ 慰 群 "问题 的 解决 方法 一 样 ， 只 有 打开 了 accept_mutex 锁 ， 才 能 
实现 worker 子 进程 间 的 负载 均衡 。 在 图 9-6 的 第 2 步 中 ， 和 初始 化 了 一 个 全 
局 变量 ngx_accept_disabled， 它 就 是 负载 均衡 机 制 实现 的 关键 国 值 ， 实 
际 上 它 束 是 一 个 整 型 数据 。 


ngx_int_t ngx_accept_disabled,; 


这 个 病 值 是 与 连接 池 中 连接 的 使 用 情况 密切 相关 的 ， 在 图 9-6 的 第 2 
筷 


步 中 它 会 进行 赋值 ， 如 下 所 示 。 


ngx_accept_disabled = ngx_cycle->connection_n/8 
- Ngx_cycle->free_connection_n,; 


因此 ， 在 Nginx 启 动 时 ，ngx_accept_disabled 的 值 就 是 一 个 负数 ， 其 
值 为 连接 总 数 的 718。 其 实 ，ngx_accept_disabled 的 用 法 很 简单 ， 当 它 为 
负数 时 ， 不 会 进行 触发 负载 均衡 操作 ， 而 当 ngx_accept_disabled 是 正 数 
时 ， 就 会 触发 Nginx 进 行 负载 均衡 操作 了 。Nginx 的 做 法 也 很 简单 ， 就 
是 当 ngx_accept_disabled 是 正 数 时 当前 进程 将 不 再 处 理 新 连接 事件 ， 取 
而 代 之 的 仅仅 是 ngx_accept_disabled 值 减 1， 如 下 所 示 。 


if (ngx_accept disabled > 0) { 
ngx_accept_disabled--; 
} else { 
If (ngx_trylock accept_ mutex(cycle) == NGX_ERROR) { 
return; 


} 


上 面 这 段 代码 表明 ， 在 当前 使 用 的 连接 到 达 总 连接 数 的 7/8 时 ， 束 
不 会 再 处 理 新 连接 了 ， 同 时 ， 在 每 次 调用 process_events 时 都 会 将 
ngx_accept_disabled 减 1， 直 到 ngx_accept_disabled 降 到 总 连接 数 的 7/8 以 
下 时 ， 才 会 调用 ngx_trylock_accept_mutex 试 图 去 处 理 新 连接 事件 。 


因此 ，Nginx 各 worker 子 进程 间 的 负载 均衡 仅 在 某 个 worker 进 程 处 
理 的 连接 数 达 到 它 最 大 处 理 总 数 的 7/8 时 才 会 触发 ， 这 时 该 worker 进 程 
就 会 减少 处 理 新 连接 的 机 会 ， 这 样 其 他 较 空 间 的 worker 进 程 束 有 机 会 去 
处 理 更 多 的 新 连接 ， 以 此 达到 整个 Web 服 务 的 均衡 处 理 效 果 。 虽 然 这 样 
的 机 制 不 是 很 完美 ， 但 在 维护 一 定 程度 上 的 负载 均衡 时 ， 很 好 地 避免 


了 当 某 个 worker 进 程 由 于 连接 池 耗 尽 而 拒绝 服务 ， 同 时 ， 在 其 他 worker 
进程 上 处 理 的 连接 还 远 未 达到 上 限 的 问题 。 因 此 ，Nginx 将 


accept_mnutex 配 置 项 默认 设 为 accept_mnutex on。 


9.8.4 ” post 事件 队 列 


上 文 已 经 介绍 过 post 事 件 的 意义 ， 本 节 来 看 一 下 post 事 件 处 理 的 实 
现 方法 。 下 面 是 两 个 post 事 件 队 列 的 定义 : 


ngx_thread_ volatile ngx event t *ngx_posted accept_events; 
ngx_thread volatile ngx event t *ngx_posted events,; 


这 两 个 指针 都 指 回 事件 队列 中 的 首 个 事件 。 这 些 事 件 间 是 以 双 辐 
链表 的 形式 组 织 成 post 事 件 队列 的 。 注 意 ，9.2 万 中 ngx_event_t 结 构 体 的 
next 和 prev 成 员 仅 用 于 post 事 件 队 列 。 


对 于 post 事 件 队 列 的 操作 方法 共有 4 个 ， 见 表 9-6。 


在 9.6.3 节 中 已 经 介绍 过 ngx_post_event 方 法 的 应 用 ， 它 会 将 事件 添 
加 a 到 队列 中 ， 那 么 ，post 事 件 什么 时 候 会 执行 呢 ? 在 9.8.5 市 我 们 束 会 介 
绍 ngx_event_process_posted 是 如 何 被 调用 的 。 


表 9-6 ”post 事 件 队 列 的 操作 方法 


方法 名 执行 意义 

ev 是 要 添加 到 post 事 件 队列 的 | 向 queue 事 件 队列 中 添加 事件 ev， 注 
事件 ，queue 是 post 事件 队列 意 ，ev 将 插入 到 事件 队列 的 首部 

线程 安 ris A 加 事 
昌 ev 在 目前 不 使 用 多 线程 的 情况 下 ， 它 
与 ngx_locked_post_event 的 功能 是 相同 和 和 

ev 是 要 从 某 个 post 事件 队 列 移 各 事件 ev 从 其 所 属 的 post 事件 队列 中 
除 的 事件 a 

cycle 是 进程 的 核心 结构 体 ngx_ 

void ngx_event_process_posted |cycle t 的 指针 ，posted 是 要 操作 的 | 调用 posted 事 件 队 列 中 所 有 事件 的 
(ngx_cycle t *cycle,ngx_thread_|post 事件 队列 ， 它 的 取 值 目前 仅 可 | handler 回调 方法 每 个 事件 调用 完 handler 
volatile ngx_event t **posted): 以 为 ngx_posted_events 或 者 ngx_ | 方法 后 ,就 会 从 posted 事件 队列 中 删除 


ngx locked post event(ev, queue) 


ev 是 要 添加 到 post 队列 的 事件 ， 


ngx post event(ev, queue) 二 和 
es 2 queue 是 post 事件 队列 


ngx delete _ posted event(ev) 


posted_accept_events 


9.8.5 “ngx_process_events_and_timers 流 程 


本 节 将 综合 上 文 相 关内 容 ， 探 讨 Nginx 事 件 框架 处 理 的 流程 。 


在 图 8-7 中 ， 每 个 worker 进 程 都 在 ngx_worker_process_cycle 方 法 中 
循环 处 理事 件 。 图 8-7 中 的 处 理 分 发 事件 实际 上 就 是 调用 的 
ngx_process_events_and_timers 方 法 ， 下 面 先 看 一 下 它 的 定义 : 


void ngx_process events and timers(ngx_cycle t *cycle); 


循环 调用 ngx_process_events_and_timers 方 法 就 是 在 处 理 所 有 的 事 
件 ， 这 正 是 事件 驱动 机 制 的 核心 。 顾 名 思 义 

ea 前 的 网 络 事件 ， 也 会 处 
理 定时 器 事件 ， 在 图 9-7 中 ， 读 者 会 看 到 在 这 个 方法 中 到 底 做 了 哪些 事 


情 。 


ngx_process_events_and_timers 方 法 中 核心 的 操作 主要 有 以 下 3 个 : 


.调用 所 使 用 的 事件 张 动 模块 实现 的 process_events 方 法 ， 处 理 网 络 
事件 。 


处理 两 个 post 事 件 队 列 中 的 事件 ， 实 际 上 束 是 分 别 调用 
ngx_event_process_posted(cycle,8&ngx_posted_accept_events) 和 和 
ngx_event_process_posted(cycle,&ngx_posted_events) 方 法 (参见 9.8.4 


字 ) 


忆 


O 〇 


:处 理 定 时 如 事件 ， 实 际 上 束 是 调用 ngx_event_expire_timers() 方 法 


(参见 9.7.3 节 ) 。 


后 两 项 操作 很 清晰 ， 而 调用 事件 驱动 模块 的 process_events 方 法 时 
则 需要 设置 两 个 关键 参数 timer 和 flags。Nginx 用 一 系列 宏 封装 了 
ngx_event_actions 接 口中 的 方法 ， 如 下 所 示 。 


#define ngx_process_ changes ngx_event actions.process changes 
#define ngx_process_events ngx_event_actions.process_events 


#define ngx_done_events ngx_event_actions.done 
#define ngx_add_event ngx_event_actions ,add 
#define ngx_del event ngx_event_actions.del 
#define ngx_add_conn ngx_event_actions.add_conn 


#define ngx_del conn ngx_event_actions.del_conn 


[使 用 timer_resolution] 


= i 这 0 


[timer_resolution 未 使 用 ] 


J ngx_event_find_timer 


2) 执 行 
得 到 最 近 超时 time 并 将 flags 设 置 为 NGX_UPDATE_TIME 
[检查 accept_mutex 锁 是 否 开 启 ] 


[accept_mutex 锁 打开 ] 


[ngx_accept disabled >0 3 jhea cc ep eT 


Hngx_trylock_accept_ 
mutex 试图 获取 accept _mutex 锁 


[检查 是 否 获取 到 了 accept _mutex 锁 ] 
ngx_accept_mutex held 为 1 表示 持 有 了 accept_mutex 锁 ] 


[ngx_accept_mutex_held 为 0 表示 未 持 有 accept_mutex 锁 ] 


5 ) 将 flags 加 入 NGX_POST_ 


6) 将 timer 设 置 为 


ngx_accept mutex_delay 


EVENTS 标 志 位 


7) 调 用 ngx_process _events 方 法 ， 
并 计算 出 耗 时 delta 


[ngx_ posted_accept_events 队列 中 有 事件 ] 


<> 


ngx_posted_accept_events 队 列 为 空 8) 执 行 ngx_posted_accept_events 
Dar 3 队列 中 的 事件 


[ngx_accept_mutex_held 为 1 表示 持 有 了 锁 ] 


《 S 
[ngx_accept_mutex_held 为 0] 9 i me 


“2 10) 调用 ngx_event_expire_timers 
[gw 执行 所 有 超时 事件 


2 11 行 . osted_events 
[ngx_posted_events 队列 为 空 ] ) Te et "i 


[ngx_process _events 方 法 耗 时 delta >0] 


[ngx_posted_events 队列 中 有 事件 ] 


2 


图 9-7 ngx_process_events_and_timers 方 法 中 的 事件 框架 处 理 流程 


在 调用 ngx_process_events 时 ， 传 入 的 timer 和 flags 会 影响 时 间 精 度 
以 及 事件 是 否 会 在 post 队 列 中 处 理 。 下 面 人 简要 分 析 一 下 图 9-7 中 的 11 个 
步骤 ， 其 中 前 6 个 步骤 都 与 参数 timer 和 flags 的 设置 有 关 。 


1) 如 果 配 置 文件 中 使 用 了 timer_resolution 配 置 项 ， 也 就 是 
ngx_timer resolution 值 大 于 0， 则 说 明 用 户 和 希望 服务 器 时 间 精 确 上 度 为 
ngXx_timer resolution 训 秒 。 这 时 ， 将 ngx_process_events 的 timer 参 数 设 
为 -1， 告 诉 ngx_process_events 方 法 在 检测 事件 时 不 要 等 每 ， 直接 搜集 
所 有 已 经 就 绪 的 事件 然后 返回 ， 同时 将 flags 参 数 初始 化 为 0， 它 是 在 告 
诉 ngx_process_events 没 有 任何 附加 动作 。 


2) 如 果 没 有 使 用 timer_resolution， 那 么 将 调用 
ngx_event_find_timer() 方 法 (参见 表 9-5) 获取 最 近 一 个 将 要 触发 的 事件 
距离 现在 有 多 少 晤 秒 ， 然 后 把 这 个 值 赋予 timer 参 数 ， 告 诉 
ngx_process_events 方 法 在 检测 事件 时 如 果 没 有 任何 事件 ， 最 多 等 行 
timer 坚 秒 葡 返回， 将 flags 参 数 设置 为 NGX_UPDATIE_TIME， 告 诉 
ngx_process_events 方 法 更 新 缓存 的 时 间 《参见 9.6.3 世 中 
ngx_epoll_process_events 方 法 的 源 代码 ) 。 


3) 如 果 在 配置 文件 中 使 用 accept_mutex off 关 闭 accept_mutex 锁 ， 
残 直 接 跳 到 第 7 步 ， 否 则 检测 负载 均衡 国 值 变量 ngx_accept_disabled。 如 


果 ngx_accept_disabled 是 正 数 ， 则 将 其 值 减 去 1， 继 续 向 下 执行 第 7 步 。 


4) 如 果 ngx_accept_disabled 是 负数 ， 表 明 还 没有 触发 到 负载 均衡 机 
制 (参见 9.8.3 节 ) ， 此 时 要 调用 ngx_trylock_accept_mutex 方 法 试图 去 获 


取 accept_mnutex 钳 | (也 就 是 ngx_accept_mutex 变 量 表示 的 锁 ) 。 


5) 如 果 获 取 到 accept_mutex 锁 ， 也 就 是 说 ，ngx_accept_mutex_held 
标志 位 为 1， 那 么 将 flags 参 数 加 上 NGX_POST_EVENTS 标 志 ， 告 诉 
ngx_process_events 方 法 搜集 到 的 事件 没有 直接 执行 它 的 handler 方 法 ， 
而 是 分 门 别 类 地 放 到 ngx_posted_accept_events 队 列 和 ngx_posted_events 
队列 中 。timer 参 数 你 持 不 变 。 


6) 如 果 没 有 获取 到 accept_mutex 锁 ， 则 意味 着 既 不 能 让 当前 worker 
进程 频繁 地 试图 抢 锁 ， 也 不 能 让 它 经 过 太 长 时 间 再 去 抢 锁 。 这 里 有 个 
人 简单 的 判断 方法 ， 如 下 所 示 。 


If (timer == NGX_TIMER_INFINITE 
|| timer > ngx_accept_mutex_delay) 


timer = ngx_accept_mutex_delay; 


} 


这 意味 着 ， 即 使 开启 了 timer_resolution 时 间 精 度 ， 也 需要 让 
ngx_process_events 方 法 在 没有 新 事件 的 时 候 至 少 等 得 
ngx_accept_mnutex_delay 室 秒 再 去 试图 抢 锁 。 而 没有 开启 时 间 精 度 时 ， 
如 果 最 近 一 个 定时 右 事 件 的 超时 时 间距 离 现 在 超过 了 


ngx_accept_mnutex_delay 训 秒 的 话 ， 也 要 把 timer 设 置 为 
ngx_accept_mnutex_delay 室 秒 ， 这 是 因为 当前 进程 虽然 没有 抢 到 
accept_mutex 锁 ， 但 也 不 能 让 ngx_process_events 方 法 在 没有 新 事件 的 时 
候 等 竺 的 时 间 超 过 ngx_accept_mnutex_delay 室 秒 ， 这 会 影响 整个 负载 均 


衡 机 制 。 


@ 注意 “ngx_accept_mutex_delay 变 量 与 nginx.conf 配 置 文件 中 的 
accept_mnutex_delay 配 置 项 的 参数 相关 内 容 可 参见 9.5:m 。 


7) 调用 ngx_process_events 方 法 ， 并 计算 ngx_process_events 执 行 时 
消耗 的 时 间 ， 如 下 所 示 。 


delta = ngx_current_msec; 
(void) ngx_process events(cycle, timer, flags); 
delta = ngx_current msec - delta; 


其 中 ，delta 是 ngx_process_events 执 行 时 消耗 的 襄 秒 数 ， 它 会 影响 
第 10 步 中 触发 定时 器 的 执行 。 


8) 如 果 ngx_posted_accept_events 队 列 不 为 空 ， 那 么 调用 
ngx_event_process_posted 方 法 执行 hgx_posted_accept_events 队 列 中 需要 
建立 新 连接 的 事件 。 


9) 如 有 果 ngx_accept_mutex_held 标 志 位 为 1， 则 表示 当前 进程 获得 了 
accept_mutex 锁 ， 而 且 在 第 8 步 中 也 已 经 处 理 完 了 新 连接 事件 ， 这 时 需 


要 调用 ngx_shmtx_unlock 释 放 accept_mutex 铅 ( 。 


10) 如 果 ngx_process_events 执 行 时 消耗 的 时 间 delta 大 于 0， 而 且 这 
时 可 能 有 新 的 定时 器 事件 被 触发 ， 那 么 需要 调用 
ngx_event_expire_timers 方 法 处 理 所 有 满足 条 件 的 定时 句 事 件 。 


11) 如 果 ngx_posted_events 队 列 不 为 空 ， 则 调用 
ngx_event_process_posted 方 法 执行 ngx_posted_events 队 列 中 的 普通 读 / 写 
事件 。 


至 此 ，ngx_process_events_and_timers 方 法 执行 完毕 。 注 意 ， 
ngx_process_events_and_timers 方 法 就 是 Nginx 实 际 上 处 理 Web 服 务 的 方 
法 ， 所 有 业务 的 执行 都 是 由 它 开始 的 。ngx_process_events_and_timers 
方法 涉及 Nginx 完 整 的 事件 驱动 机 制 ， 因 此 ， 它 也 把 之 前 介绍 的 内 容 整 
合 在 一 起 了 ， 读 者 需要 格外 注意 。 


9.9 文件 的 异步 IO 


本 章 之 前 提 到 的 事件 驱动 模块 都 是 在 处 理 网 络 事件 ， 而 没有 涉及 
磁盘 上 文件 的 操作 。 本 节 将 讨论 Linux 内 核 2.6.2x 之 后 版 本 中 支持 的 文 
件 异步 WJO， 以 及 ngx_epoll_module 模 块 是 如 何 与 文件 异步 WO 配合 提供 
服务 的 。 这 里 提 到 的 文件 异步 WO 并 不 是 glibc 库 提供 的 文件 异步 WO。 
glibc 库 提供 的 异步 JO 是 基于 多 线程 实现 的 ， 它 不 是 真正 意义 上 的 异步 
IO。 而 本 节 说 明 的 异步 0O 是 由 Linux 内 核实 现 ， 只 有 在 内 核 中 成 功 地 
完成 了 磁盘 操作 ， 内 核 才 会 通知 进程 ， 进 而 使 得 磁盘 文件 的 处 理 与 网 
络 事件 的 处 理 同 样 高 效 。 


使 用 这 种 方式 的 前 提 是 Linux 内 核 版 本 中 必须 文 持 文件 异步 JO。 当 
然 ， 它 带 来 的 好 处 也 非常 明显 ，Nginx 把 读 取 文件 的 操作 异步 地 提交 给 
内 核 后 ， 内 核 会 通知 VO 设备 独立 地 执行 操作 ， 这 样 ，Nginx 进 程 可 以 继 
续 充 分 地 占用 CPU。 而 且 ， 当 大 量 读 事 件 堆积 到 IO 设备 的 队列 中 时 ， 
将 会 发 挥 出 内 核 中 * 电 梯 算 法 ”的 优势 ， 从 而 降低 随机 读 取 磁盘 而 区 的 
成 本 。 


@ 注音 Linux 内 核 级 别 的 文件 异步 UO 是 不 支持 缓存 操作 的 ， 也 
就 是 说 ， 即 使 需要 操作 的 文件 块 在 Linux 文 件 缓存 中 存在 ， 也 不 会 通过 
读 取 、 更 改 缓存 中 的 文件 块 来 代替 实际 对 磁盘 的 操作 ， 虽 然 从 阻塞 


worker 进 程 的 角度 上 来 说 有 了 很 大 好 转 ， 但 是 对 单个 请 求 来 说 ， 还 是 有 
可 能 降低 实际 处 理 的 速度 ， 因 为 原先 可 以 从 内 存 中 快速 获取 的 文件 块 
在 使 用 了 异步 WO 后 则 一 定 会 从 磁盘 上 读 取 。 有 异步 文 件 WO 是 把 “ 双 丸 
全 ”关键 要 看 使 用 场景 ， 如 琳 大 部 分 用 户 请 求 对 文件 的 操作 都 会 落 到 
文件 缓存 中 ， 那 么 不 要 使 用 异步 JO， 反 之 则 可 以 试 着 使 用 文件 异步 
LIUO， 看 一 下 有 是否 会 为 服务 市 来 并 发 能 力 上 的 提升 。 


目前 ，Nginx 仅 支持 在 读 取 文 件 时 使 用 异步 WO， 因 为 正常 写 入 文件 
时 往往 是 写 入 内 存 中 就 立刻 返回 ， 效 率 很 高 ， 而 使 用 异步 JO 写 入 时 速 


度 会 明显 下 降 。 


9.9.1 Linux 内 核 提 供 的 文件 异步 1/O 


Linux 内 核 提供 了 5 个 系统 调用 完成 文件 操作 的 异步 WO 功能 ， 见 表 
9-7° 


表 9-7 Linux 内 核 提 供 的 文件 异步 1/O 操 作 方 法 


方法 名 执行 意义 
初始 化 文件 异步 IO 的 上 下 文 ， 
nr_events 表示 需要 初始 化 的 异步 也 | 执行 成 功 后 ctxp 就 是 分 配 的 上 下 
O 上 下 文 可 以 处 理 的 事件 的 最 小 个 数 , | 文 描述 符 ， 这 个 异步 WO 上 下 文 
ctxp 是 文件 异步 IO 的 上 下 文 描述 符 指针 | 将 至 少 可 以 处 理 nr_events 个 事 
件 。 返回 0 表示 成 功 
销毁 文件 异步 IO 的 上 下 文 
返回 0 表示 成 功 


int 10_setup(unsigned nr _events. 


alo_context t *ctxp) 


int io_destroy (aio_context t ctx) ctx 是 文件 异步 IO 的 上 下 文 描述 符 


ctx 是 文件 异步 IO 的 上 下 文 描 述 符 ， 
nr 是 一 次 提交 的 事件 个 数 ，cbp 是 需要 
是 交 的 事件 数组 中 的 首 个 元 素 地 址 

ctx 是 文件 异步 WO 的 上 下 文 描 述 符 ,| 取消 之 前 使 用 io_sumbit 提 交 
iocb 是 要 取消 的 异步 IO 操作 ， 而 result | 的 一 个 文件 异步 IO 操作。 返回 
表示 这 个 操作 的 执行 结果 0 表示 成 功 

ctx 是 文件 异步 IO 的 上 下 文 描述 符 ; 


是 交 文 件 异 步 VO 操作。 返回 
值 表示 成 功 提交 的 事件 个 数 


int io_submit(aio_context t ctx, 


long nr, struct iocb *cbp[]) 


int io_cancel(aio_context t ctx. struct 


iocb *iocb, struct 10_event *result) 


min nt 表示 至 少 要 获取 min nr 个 事件 ; 


int io_ getevents(aio_context t ctx, WK eb 
而 nr 表示 至 多 获取 冬 个 事件 ， 它 与 
events 数组 的 个 数 一 般 是 相同 的 ; events 
是 执行 完成 的 事件 数组 ; timeout 是 超时 
时 间 ， 也 就 是 在 获取 min_nr 个 事件 前 的 
等 待 时 间 


从 已 经 完成 的 文件 异步 IO 操 
作 队 列 中 读 取 操作 


long min_nr, long nr. 
struct 10_event *events, struct 


timespec *timeout) 


表 9-7 中 列举 的 这 5 种 方法 提供 了 内 核 级 别 的 文件 异步 WO 机 制 ， 使 

用 前 需要 先 调 用 io_setup 方 法 初始 化 异步 WO 上 下 文 。 虽 然 一 个 进程 可 以 
拥有 多 个 异步 WO 上 下 文 ， 但 通 稼 有 一 个 就 足够 了 。 调 用 io_setup 方 法 后 
会 获得 这 个 异步 WO 上 下 文 的 描述 符 (aio_context_t 类 型 ， 这 个 描述 符 
和 epoll_create 返 回 的 描述 符 一 样 ， 是 贯穿 始终 的 。 注 意 ，nr_events 只 是 
指定 了 异步 WO 人 至少 初 始 化 的 上 下 文 容量 ， 它 并 没有 限制 最 大 可 以 处 理 
的 异步 /O 事 件数 日 。 为 了 便于 理解 ， 不 妨 将 io_setup 写 epoll_create 进 行 
对 比 ， 它 们 还 是 很 相似 的 。 


既然 把 epoll 和 异步 1/O 进 行 对 比 ， 那 么 哪些 调用 相当 于 epoll_ctrl 
呢 ? 就 是 io_submit 和 io_cancel。 其 中 io_submit 相 当 于 向 异 步 WO 中 添加 


事件 ， 而 io_cancel 则 相当 于 从 异步 /O 中 移 除 事件 。io_submit 中 用 到 了 
一 个 结构 体 iocb， 下 面 简 单 地 看 一 下 它 的 定义 。 


struct iocb 


{ 
/* 存 储 着 业务 需要 的 指针 。 例 如 ， 在 


Nginx 中 ， 这 个 字段 通常 存储 着 对 应 的 


ngx_event_t 事 件 的 指针 。 它 实际 上 与 


io_getevents 方 法 中 返回 的 


io_event 结 构 体 的 
data 成 员 是 完全 一 致 的 


*/ 


U_int64 t aio_ data,; 
// 不 需要 设 


U_int32_t PADDED(aio_key, aio_reserved1); 
// 操作 码 ， 其 取 值 范围 是 


io_iocb_cmd_t 中 的 枚 举 命 令 


u_int16_t aio lio opcode; 


// 请 求 的 优先 级 


int16_t aio_reqprio; 
// 文件 描述 符 


U_int32_t aio_fildes,; 
// 读 


/ 写 操作 对 应 的 用 户 态 缓冲 


[x| 


U_int64 t aio_buf， 
// 读 


/ 写 操作 的 字 节 长 度 


U_int64 t aio_nbytes 
// 读 


/ 写 操 作对 应 于 文件 中 的 偏 移 量 


int64_t alio_offset ， 
// 保留 字段 


U_int64 t aio_reserved2 


/* 表 示 可 以 设置 为 


IOCB_FLAG_RESFD， 它 会 告诉 内 核 当 有 异步 


I/0 请 求 处 理 完成 时 使 用 


eventfd 进 行 通知 ， 可 与 


epoll 配 合 使 用 ， 其 在 


Nginx 中 的 使 用 方法 可 参见 


9.9.2 市 


*/ 
u_int32_t aio_ flags; 
// 表示 当 使 用 


IO0CB_FLAG_RESFD 标 志 位 时 ， 用 于 进行 事件 通知 的 句柄 


U_int32 t aio_resfd; 


}; 


因此 ， 在 设置 好 iocb 结 构 体 后 ， 束 可 以 同 异 步 WO 提 交 事 件 了 。 
aio_lio_opcode 操 作 码 指定 了 这 个 事件 的 操作 类 型 ， 它 的 取 值 范围 如 
下 o 


typedef enum io_iocb_cmd { 
// 异步 读 操作 


IO_CMD_PREAD = 0, 
// 异步 写 操作 


IO_CMD_PWRITE = 1, 
// 强制 同步 


IO_CMD_FSYNC = 2， 
// 目前 未 使 


IO_CMD_FDSYNC = 3, 
// 目前 未 使 用 


IO_CMD_POLL = 5, 
// 不 做 任何 事情 


IO_CMD_NOOP = 6， 
} io_iocb_cmd tt， 


在 Nginx 中 ， 仅 使 用 了 IO_CMD_PREAD 命 令 ， 这 是 因为 目前 仅 支 
持 文 件 的 异步 /JO 读 取 ， 不 支持 异步 /O 的 写 入 。 这 其 中 一 个 重要 的 原因 
是 文件 的 异步 WO 无 法 利用 缓存 ， 而 写 文 件 操 作 通 常 是 落 到 缓存 中 的 ， 
Linux 存 在 统一 将 缓存 中 “ 脏 ” 数 据 刷 狐 到 磁盘 的 机 制 。 


这 样 ， 使 用 io_submit 品 内核 所 区 了 文件 异步 JO 操 作 的 事件 后 ， 再 
使 用 io_cancel 则 可 以 将 已 经 提交 的 事件 取消 。 


如 何 获取 已 经 完成 的 异步 JO 事 件 呢 ? io_getevents 方 法 可 以 做 到 ， 
它 相 当 于 epoll 中 的 epoll_wait 方 法 。 这 里 用 到 了 io_event 结 构 体 ， 下 面 看 
一 下 它 的 定义 。 


struct io event f{ 
// 与 提交 事件 时 对 应 的 


iocb 结 构 体 中 的 


aio_data 是 一 致 的 


Uint64 t data; 
// 指向 提交 事件 时 对 应 的 


iocb 结 构 体 


uint64 _t obj; 
// 异步 


I/0 请 求 的 结构 。 
res 大 于 或 等 于 
0 时 表示 成 功 ， 小 于 


9 时 表示 失败 


Int64 上 res; 
// 保留 字段 


int64_t res2; 


这 样 ， 根 据 获 取 的 io_event 结 构 体 数组 ， 就 可 以 获得 已 经 完成 的 异 
步 /O 操 作 了 ， 特 别 是 iocb 结 构 体 中 的 aio_data 成 员 和 io_event 中 的 data， 
可 用 于 传递 指针 ， 也 就 是 说 ， 业 务 中 的 数据 结构 、 事 件 完 成 后 的 回调 
方法 都 在 这 里 。 


进程 退出 时 需要 调用 io_destroy 方 法 销毁 异步 JO 上 下 文 ， 这 相当 于 
调用 close 天 闭 epoll 的 描述 伯 。 


Linux 内 核 提 供 的 文件 异步 VO 机 制 用 法 非常 简单 ， 它 充分 利用 了 在 
内 核 中 CPU 与 VO 设备 是 各 自 独立 工作 的 这 一 特性 ， 在 提交 了 异步 /O 操 
作 后 ， 进 程 完全 可 以 做 其 他 工作 ， 直 到 空 闪 再 来 查看 异步 1O 操 作 是 否 
完成 。 


9.9.2 ”ngx_epoll_module 模 块 中 实现 的 针对 文件 的 异步 1/O 


在 Nginx 中 ， 文 件 异步 /O 事 件 完 成 后 的 通知 是 集成 到 epoll 中 的 ， 它 
是 通过 9.9.1 节 中 介绍 的 IOCB_FLAG_RESFD 标 志 位 完成 的 。 下 面 看 看 
文件 异步 IO 事件 在 ngx_epoll_ module 模 块 中 是 如 何 实现 的 ， 其 中 在 文件 
异步 WO 机 制 中 定义 的 全 局 变量 如 下 。 


// 用 于 通知 异步 


I/0 事 件 的 描述 符 ， 它 与 


iocb 结 构 体 中 的 


aio_resfd 成 员 是 一 致 的 


int ngx_eventfd = -1; 
// 异步 


I/0 的 上 下 文 ， 全 局 唯一 ， 必 须 经 过 


io_setup 初 始 化 才能 使 


aio_context_t ngx_aio ctx = 0; 
/* 异 步 


I/0 事 件 完 成 后 进行 通知 的 描述 符 ， 也 就 是 


ngx_eventfd 所 对 应 的 


ngx_event_t 事 但 


:A 
static ngx_event_t ngx_eventfd_ event; 
/* 异 步 


I/0 事 件 完成 后 进行 通知 的 描述 符 


ngx_eventfd 所 对 应 的 
ngx_connection_t 连 接 


"A 
static ngx_connection_t ngx_eventfd_conn; 


在 9.6.3 广 的 ngx_epoll_init 代 码 中 ， 在 epoll_create 执 行 完 成 后 如 采 开 
局 了 文件 异步 IO 功能 ， 则 会 调用 ngx_epoll_aio_init 方 法 。 现 在 详细 描 
述 一 人 ngx_epoll_aio_init 方 法 中 做 了 些 人 什么， 如 下 所 示 。 


#define SYS_eventfd 323 
static void ngx_epoll aio init(ngx_cycle t *cycle, ngx_epoll conf_t *epcf) 
{ 

int n; 

struct epoll event ee; 

// 使 


Linux 中 第 


323 个 系统 调用 获取 一 个 描述 符 句柄 


ngx_eventfd = syscall(SYS eventfd, 0); 


// 设置 


ngx_eventfd 为 无 阻塞 


if (ioctl(ngx_eventfd, FIONBIO，&n) == -1) { 


} 
// 初始 化 文件 异步 


I/0 的 上 下 文 
If (io_setup(epcf->aio_requests, &ngx_aio ctx) == -1) { 
} 
/* 设 置 用 于 异步 


I/0 完 成 通知 的 


ngx_eventfd_event 事 件 ， 它 与 
ngx_eventfd_conn 连 接 是 对 应 的 
4 

ngx_eventfd_event ,data = &ngx_eventfd_conn,; 


// 在 异步 
I/0 事 件 完 成 后 ， 使 用 


Hr 


ngx_epoll_eventfd_handler 方 法 处 理 


ngx_eventfd_event ,handler = ngx_epoll eventfd handler,; 
ngx_eventfd_event ,1og = Cycle->1o0g 

ngx_eventfd_event ,active = 1; 

// 初始 化 


ngx_eventfd_conn 连 接 


ngx_eventfd_conn.fd = ngx_eventfd,; 
// ngx_eventfd_conn 连 接 的 读 事件 就 是 上 面 的 


ngx_eventfd_event 
ngx_eventfd_conn.read = &ngx_eventfd_event ; 
ngx_eventfd_conn,1og = cycle->10g; 
ee.events = EPOLLIN|EPOLLET ， 
ee.data.ptr = &ngx_eventfd_conn; 
// 向 


epoll 中 添加 到 异步 


I/0 的 通知 描述 符 


ngx_eventfd 
If (epoll ctl(ep, EPOLL_CTL_ADD, ngx_eventfd, &ee) != -1) { 
return; 


} 


这 样 ，ngx_epoll_aio_init 方 法 会 把 异步 IO 与 epoll 结 合 起 来 ， 当 某 
一 个 异步 IO 事件 完成 后 ，ngx_eventfd 句 柄 就 处 于 可 用 状态 ， 这 样 
epoll_wait 在 返回 ngx_eventfd_event 事 件 后 就 会 调用 它 的 回调 方法 
ngx_epoll_eventfd_handler 处 理 已 经 完成 的 异步 /0O 事 件 ， 下 面 看 一 下 
ngx_epoll_eventfd_handler 方 法 主要 在 做 些 什 么 ， 代 码 如 下 所 示 。 


static void ngx_epoll eventfd_ handler(ngx_event_t *ev) 


int n, events,; 
uint64_t ready; 
ngx_event_t *e,; 
// 一 次 性 最 多 处 理 


64 个 事件 


struct io_event event[64]; 
struct timespec ts; 
/* 获 取 已 经 完成 的 事件 数目 ， 并 设置 到 


i 


ready 中 ， 注 意 ， 这 个 


ready 是 可 以 大 于 


64 的 


*/ 
n = read(ngx_eventfd, &ready, 8); 


Ts 


// ready 表 示 还 未 处 理 的 事件 。 


ready 大 于 
9 时 继续 处 理 


while (ready) { 
// 调 


io_getevents 获 取 已 经 完成 的 异步 


I/0 事 件 


events = io_getevents(ngx_aio ctx, 1, 64, event, &ts); 
If (events > 0) { 
// 将 


ready 减 去 已 经 取出 的 事件 


ready -= events; 
// 处 理 


event 数 组 里 的 事件 


for (i = 0; i < events; i++) { 
// data 成 员 指 向 这 个 异步 


I/0 事 件 对 应 着 的 实际 事件 


er 


e = (ngx_event t *) (uintptr_t) event[i].data; 


// 将 该 事件 放 到 


ngx_posted_events 队 列 中 延 后 执行 


ngx_post_event(e，&ngx_posted_events ) ， 
continue; 


If (events == 0) { 
return; 
} 


return; 


整个 网 络 事件 的 驱动 机 制 束 是 这 样 通过 ngx_eventfd 通 知 朱 述 符 和 
ngx_epoll_eventfd_handler 回 调 方法 ， 并 与 文件 异步 JO 事 件 结合 起 来 
阿 。 


那么 ， 怎 样 回 异步 JO 上 下 文中 提交 异步 MO 操作 呢 ? 看 看 
ngx_linux_aio_read.c 文 件 中 的 ngx_file_aio_read 方 法 ， 在 打开 文件 异步 
IO 后 ， 这 个 方法 将 会 负责 佩 一 文件 的 读 取 ， 如 下 所 示 。 


ssize t ngx_file aio read(ngx_file t *file, u_char *buf, size t size, off_t 
offset, ngx_pool t *pool) 


{ 
ngx_err_t err; 
struct iocb *piocb[1]; 
ngx_event_t *ev; 


ngx_event _ aio t *aio; 


aio = file->aio,; 
ev = &aio->event,; 


ngx_memzero(&aio->aiocb, sizeof(struct iocb)); 
/* 设 置 


9.9.1 市 中 介绍 过 的 


iocb 结 构 体 ， 这 里 的 


aiocb 成 员 就 是 


iocb 类 型 。 注 意 ， 


aio_data 已 经 设置 为 这 个 


ngx_event_t 事 件 的 指针 ， 这 样 ， 从 


io_getevents 方 法 获取 的 


io_event 对 象 中 的 


data 也 是 这 个 指针 


i 
aio->aiocb.aio data = (uint64 t) (uintptr_t) ev; 
aio->aiocb.aio_lio _ opcode = IOCB_CMD_PREAD; 
aio->aiocb.aio_fildes = file->fd; 
aio->aiocb.aio_buf = (uint64 _t) (uintptr_t) buf,; 
aio->aiocb.aio_nbytes = size; 
aio->aiocb.aio_ offset = offset,; 
aio->aiocb.aio_flags IOCB_FLAG_RESFD; 
aio->aiocb.aio_resfd ngx_eventfd; 


/* 设 置 事件 的 回调 方法 为 


ngx_file_aio_event_handler， 它 的 调用 关系 类 似 这 样 


:epo11_wait 中 调 


ngx_epoll_eventfd_handler 方法 将 当前 事件 放 入 到 


ngx_posted_events 队 列 中 ， 在 延 后 执行 的 队列 中 调用 


ngx_file_aio_event_handler 方 法 


SA 
ev->handler = ngx_file aio event_ handler; 
piocb[0] = &aio->aiocb; 

/* 调 用 


io_submit 向 
ngx_aio_ctx 异 步 


I/0 上 下 文中 添加 


1 个 事件 ， 返 加 


1 表示 成 功 
*/ 
If (io_submit(ngx_aio ctx, 1, piocb) == 1) { 
ev->active = 1; 
ev->ready = 9; 
ev->complete = 0; 
return NGX_AGAIN ， 
} 
} 


下 面 看 一 下 ngx_event_aio_t 结 构 体 的 定义 。 


typedef struct ngx_event aio_s ngx_event_aio_t; 
struct ngx_event aio s { 

void *data; 

// 这 是 真正 由 业务 模块 实现 的 方法 ， 在 异步 


I/0 事 件 完成 后 被 调 


ngx_event_handler_pt handler; 
ngx_file t *file,; 
ngx_fd_t fd; 
#if (NGX_HAVE_EVENTFD ) 
Int64_t res,; 
#else 
ngx_err_t err,; 
size_t nbytes,; 
#endif 
#if (NGX_HAVE_AIO_SENDFILE) 
off_t last_offset,; 
#endif 
// 这 里 的 


ngx_aiocb_t 就 是 


9.9.1 市 中 介绍 的 


iocb 结 构 体 
ngx_aiocb_t aiocb; 
BCeventE eventi 
这 样 ，ngx_file_aio_read 方 法 会 回 异 步 JO 上 下 文中 添加 事件 ， 该 
epoll_wait 在 通过 ngx_eventfd 摘 述 符 检测 到 异步 JO 事 件 后 ， 会 再 调用 
ngx_epoll_eventfd_handler 方 法 将 io_event 事 件 取 出 来 ， 放 入 
ngx_posted_events 队 列 中 延 后 执行 。ngx_posted_events 队 列 中 的 事件 执 
行 时 ， 则 会 调用 ngx_file_aio_event_handler 方 法 。 下 面 看 一 下 
ngx_file_aio_event_handler 方 法 做 了 些 什 么 ， 代 码 如 下 所 示 。 


static void ngx_file aio event_handler(ngx_event_t *ev) 


ngx_event _ aio t *aio; 
aio = ev->data; 
aio->handler (ev); 


} 


这 里 调用 了 ngx_event_aio_t 结 构 体 的 handler 回 调 方法 ， 这 个 回调 方 
法 下 由 真正 的 业务 模块 实现 的 ， 也 束 是 说 ， 任 一 个 业务 模块 想 使 用 文 
件 异 步 JO， 束 可 以 实现 handler 方 法 ， 这 样 ， 在 文件 异步 操作 完成 后 ， 
该 方法 束 会 被 回调 。 


9.10 TCP 协议 与 Nginx 


作为 Web 服 务 器 的 nginx， 主 要 任务 当然 是 处 理 好 基于 TCP 的 HTTP 
协议 ， 本 节 将 深入 TCP 协 议 的 实现 细节 (Qinux 下 ) 以 更 好 地 理解 Nginx 
事件 处 理 机 制 。 


TCP 是 一 个 面向 连接 的 协议 ， 它 必须 基于 建立 好 的 TCP 连 接 来 为 通 
信 的 两 方 提供 可 靠 的 字 节 流 服 务 。 建 立 TCP 连 接 是 我 们 耳熟能详 的 三 次 
EE 

1) 客户 端 向 服务 器 发 起 连接 (SYN) 。 

2) 服务 右 确 认 收 到 并 癌 客 户 端 也 发 起 连接 (ACK+SYN) 。 

3) 客户 端 确认 收 到 服务 器 发 起 的 连接 (ACK) 。 


这 个 建立 连接 的 过 程 是 在 操作 系统 内 核 中 完成 的 ， 而 如 Nginx 这 样 
的 应 用 程序 只 是 从 内 核 中 取出 已 经 建立 好 的 TCP 连 接 。 大 多 时 候 ， 
Nginx 征 作为 连接 的 服务 硕 方 存在 的 ， 我 们 看 一 看 Linux 内 核 是 怎样 处 
理 TCP 连 接 建 立 的 ， 如 图 9-8 所 示 。 


1.2 搬 和 人 队列 


济 吴 < 


2.2 由 队列 中 取出 


.3 插入 队列 


3 调用 accept 取 出 连接 套 接 字 


A 
CE 
E 
P 
Tn 
队 
列 


图 9-8 ”服务 器 端 建立 TCP 连 接 的 简化 示意 图 


图 9-8 中 简单 地 表达 了 一 个 观点 : 内 核 在 我 们 调用 listen 方 法 时 ， 恕 
已 经 为 这 个 监听 端口 建立 了 SYN 队 列 和 ACCEPT 队 列 ， 当 客户 端 使 用 
connect 方 法 向 服务 器 发 起 TCP 连 接 ， 随 后 图 中 1.1 步 又 客户 端的 SYN 包 
到 达 了 服务 器 后 ， 内 核 会 把 这 一 信息 放 到 SYN 队 列 ( 即 未 完成 握手 队 
列 ) 中 ， 同 时 回 一 个 SYN+ACK 包 给 客户 端 。2.1 步 骤 中 客户 端 再 次 发 
来 了 针对 服务 器 SYN 包 的 ACK 网 络 分 组 时 ， 内 核 会 把 连接 从 SYN 队 列 
中 取出 ， 再 把 这 个 连接 放 到 ACCEPT 队 列 〈 即 已 完成 握手 队列 ) 中 。 而 


服务 器 在 第 3 步调 用 accept 方 法 建立 连接 时 ， 其 实 就 是 直接 从 ACCEPT 
队列 中 取出 已 经 建 好 的 连接 而 已 。 


这 样 ， 如 果 大 量 连接 同时 到 来 ， 而 应 用 程序 不 能 及 时 地 调用 accept 
方法 ， 就 会 导致 以 上 两 个 队列 满 (ACCEPT 队 列 满 ， 进 而 也 会 导致 SYN 
队列 满 ) ， 从 而 导致 连接 无 法 建立 。 这 其 实 很 常见 ， 比 如 Nginx 的 每 个 
worker 进 程 都 负责 调用 accept 方 法 ， 如 果 一 个 Nginx 模 块 在 处 理 请 求 时 长 
时 间 陷 入 了 某 个 方法 的 执行 中 (如 执行 计算 或 者 等 待 IO) ， 束 有 可 能 
导致 新 连接 无 法 建立 。 


建立 好 连接 后 ，TCP 提 供 了 可 靠 的 字 节 流 服务 。 怎 么 理解 所 谓 
的 “可 靠 " 呢 ? 可 以 简单 概括 为 以 下 4 点 : 


1) TCP 的 send 方 法 可 以 发 送 任意 大 的 长 度 ， 但 数据 链 路 层 不 会 允 
许 一 个 报 文 太 大 的 ， 当 报 文 长 度 超过 MTU 大 小 时 ， 它 一 定 会 把 超大 的 
报 文 切 成 小 报 文 。 这 样 的 场景 是 不 侯 TCP 接 受 的 ， 切 分 报 文 段 既 然 不 可 
和 避免， 那么 束 只 能 发 生 在 TCP 协 议 内 部 ， 这 才 是 最 有 效率 的 。 


2) 每 一 个 报 文 在 发 出 后 都 必须 收 到 “回执 “一 一 ACK， 确 保 对 方 收 
到 ， 和 否则 会 在 超时 时 间 达 到 后 重 发 。 相 对 的 ， 接 收 到 一 个 报 文 时 也 必 
须发 送 一 个 ACK 告 诉 对 方 。 


3) 报 文 在 网 络 中 传输 时 会 失 序 ，TCP 接 收 端 需要 重新 排序 失 序 的 
报 文 ， 组 合成 发 送 时 的 原 序 再 给 到 应 用 程序 。 当 然 ， 重 复 的 报 文 也 要 


去 疗 ” 


4) 当 连 接 的 两 端 处 理 速度 不 一 臻 时， 为 防止 TCP 缓 冲 区 溢出 ， 还 
要 有 个 流量 控制 ， 减 组 速度 更 快 一 方 的 发 送 速 度 。 


从 以 上 4 点 可 以 看 到 ， 内 核 为 每 一 个 TCP 连 接 都 分 配 了 内 存 分 别 充 
当 发 送 、 接 收 缓冲 区 ， 这 与 Nginx 这 种 应 用 程序 中 的 用 户 态 缓存 不 同 。 
搞 清 楚 内 核 的 TCP 读 写 绥 存 区 ， 对 于 我 们 判断 Nginx 的 处 理 能 力 很 有 帮 
助 ， 毕 竟 无 论 内 核 还 是 应 用 程序 都 在 抢 物理 内 存 。 


先 来 看 看 调用 send 这 样 的 方法 发 送 TCP 字 地 流 时 ， 内 核 到 底 做 了 哪 
些 事 。 图 9-9 是 一 个 简单 的 send 方 法 调用 时 的 流程 示意 图 。 


TCP 连 接 建 立时 ， 就 可 以 判断 出 双方 的 网 络 间 最 适宜 的 、 不 会 被 再 
次 切 分 的 报 文大 小 ，TCP 层 把 它 叫 做 MSS 最 大 报 文 段 长 度 (当然 ，MSS 
是 可 变 的 ) 。 在 图 9-9 的 场景 中 ， 假 定 待 发 送 的 内 存 将 按照 MSS 被 切 分 
为 3 个 报 文 ， 应 用 程序 在 第 1 步调 用 send 方 法 、 第 10 步 send 方 法 返回 之 
间 ， 内 核 的 主要 任务 是 把 用 户 态 的 内 存 内 容 找 贝 到 内 核 态 的 TCP 缓 冲 区 
上 ， 在 第 5 步 时 假定 内 核 缓存 区 暂时 不 足 ， 在 超时 时 间 内 又 等 到 了 足够 
的 空闲 空间 。 从 图 中 可 以 看 到 ，send 方 法 成 功 返 回 并 不 等 于 就 把 报 文 发 
送出 去 了 (当然 更 不 等 于 对 方 接收 到 了 报 文 )。 


取出 MSS 分 组 发 送 


snd_imeo 时 间 内 等 和 有 空间 的 组 存 | 用 
send 方 法 | rs 和 


按 Nagle、 慢 启动 等 算法 发 关 报 | 


轿 3) 复制 到 内 核 态 


MSS 分 组 1 


循环 地 将 待 发 送 字符 
流 分 成 MSS 分 组 拷贝 
到 内 核 态 


6 ) 超时 或 有 空闲 缓存 ey 


8) tcp_push 


1 ) 调用 send 发 送 


10 ) 全 部 或 者 部 分 发 送 


图 9-9 send 方 法 执行 时 的 流程 示意 图 


当 调用 recv 这 样 的 方法 接收 报 文 时 ，Nginx 是 基于 事件 驱动 的 ， 也 


就 是 说 只 有 epoll 通 知 worker 进 程 收 到 了 网 络 报 文 ，recv 才 会 被 调用 


socket 也 被 设 为 非 阻 塞 模式 ) 


。 图 9-10 束 是 一 个 这 样 的 场景 ， 在 第 
1~4 步 表示 接收 到 了 无 序 的 报 文 后 ， 内 核 是 怎样 重新 排序 的 。 第 5 步 开 
台 ， 应 用 程序 调用 了 recv 方 法 ， 内 核 开 始 把 TCP 读 缓冲 区 的 内 容 捞 贝 到 


应 用 程序 的 用 户 态 内 存 中 ， 第 13 步 recv 方 法 返回 拷贝 的 字 市 数 。 图 中 用 
到 了 linux 内 核 中 为 TCP 准 备 的 2 个 队列 : receive 队 列 是 允许 用 户 进程 直 
接 读 取 的 ， 它 是 将 已 经 接收 到 的 TCP 报 文 ， 去 除了 TCP 头 部 、 排 好 序 放 
入 的 、 用 户 进 程 可 以 直接 按 序 读 取 的 队列 ; out_of_order 队 列 存放 乱 序 
六 


回 过 头 来 看 ，Nginx 使 用 好 TCP 协 议 主要 在 于 如 何 有 效率 地 使 用 
CPU 和 内 存 。 只 在 必要 时 才 调 用 TCP 的 send/recv 方 法 ， 这 样 就 避免 了 无 
谓 的 CPU 浪 费 。 例 如 ， 只 有 接收 到 报 文 ， 其 至 只 有 接收 到 足够 多 的 报 
文 (SO_RCVLOWAT 阔 值 ) ，worker 进 程 才 有 可 能 调用 recv 方 法 。 同 
样 ， 只 在 发 送 缓冲 区 有 空闲 空间 时 才 去 调用 send 方 法 。 这 样 的 调用 才 是 
有 效率 的 。Nginx 对 内 存 的 分 配 是 很 节俭 的 ， 但 Linux 内 核 使 用 的 内 存 
又 如 何 控制 呢 ? 


服务 器 


Linux 内 核 


4 ) 遍历 out_of_order 取 出 S3-S4 放 入 receive 队 列 


) 复制 到 用 户 态 


“3 ) 所 | 寻 民 文 52- Soh 和 eceiveB 人 | 
) 接收 到 失 序 的 S3-S4， 插 入 out_of order 重 


> 


7 ) 处 理 receive 队 列 中 已 排序 的 报 文 。 “5 ) 调用 recv 接 收 阻塞 socket 
11 ) 返回 


锁 住 Socket， 获 取 


最 低 接 收 阐 值 


| ”检查 是 否 接收 到 
超过 最 低 阅 值 的 


13 ) recv 方 法 返回 已 经 拷贝 的 S4-S1 字 节 数 


TCP 消 息 长 度 6 ) tcp_recvmsg 


12 ) 已 经 拷贝 的 字 节 数 超过 最 低 接收 病 值 ， 
而 且 backlog 队 列 为 室 


图 9-10 recv 方 法 执行 时 的 流程 示意 图 


首先 ， 我 们 可 以 控制 内 存 缓存 的 上 限 ， 例 如 基于 setsockopt 方 法 实 
现 的 SO_SNDBUF、SO_RCVBUF (Nginx 的 listen 配 置 里 的 sndbuf 和 
rcvbuf 也 是 在 改 它 们 ， 参 见 2.4.1 节 ) 。SO_SNDBUF 表 示 这 个 连接 上 的 
内 核 写 缓存 上 限 (事实 上 SO_SNDBUF 也 并 不 是 精确 的 上 限 ， 在 内 核 中 
会 把 这 个 值 翻 一 倍 再 作为 写 缓存 上 限 使 用 ) 。 它 受制 于 系统 级 配置 的 
上 下 限 net.core.wmem_max (参见 1.3.4 节 ) 。SO_RCVBUF 同 理 。 读 写 
缓存 的 实际 内 存 大 小 与 场景 有 关 。 对 读 缓存 来 说 ， 接 收 到 一 个 来 自 连 
接 对 端的 TCP 报 文 时 ， 会 导致 读 缓存 增加 ， 如 果 超 过 了 读 缓存 上 限 ， 那 


么 这 个 报 文 会 被 丢 痉 。 当 进程 调用 read、recv 这 样 的 方法 读 取 字 节 流 
时 ， 读 缓存 束 会 减少 。 因此 ， 读 绥 存 古 一 个 动态 变化 的 、 实 际 用 到 多 
少 才 分 配 多 少 的 缓冲 内 存 。 当 用 户 进 程 调用 send 方 法 发 送 TCP 字 户 流 
时 ， 整 会 造成 写 绥 存 增 大 。 当 然 ， 如 琳 写 缓存 已 经 到 达 上 限 ， 那 么 写 
缓存 维持 不 变 ， 辐 用 户 进 程 返 回 失败 。 而 每 当 接收 到 连接 对 端 发 来 的 
ACK， 确 认 了 报 文 的 成 功 发 送 时 ， 写 缓存 束 会 减少 。 可 见 缓存 上 限 所 
起 作用 为 : 丢弃 新 报 文 ， 防止 这 个 TCP 连 接 消耗 太 多 的 内 存 。 


其 次 ， 我 们 可 以 使 用 Linux 提 供 的 目 动 内 存 调整 功能 。 
net.ipv4.tcp moderate_rcvbuf = 1 


默认 tcp_moderate_rcvbuf 配 置 为 7， 表示 打开 了 了 TCP 内存 目 动 调整 功 
能 。 若 配置 为 0， 这 个 功能 将 不 会 生效 ( 慎 用 ) 


@@ 广 意 。 当 我 们 在 编程 中 对 连接 设置 了 SO_SNDBUE 、 
SO_RCVBUF， 将 会 使 Linux 内 核 不 再 对 这 样 的 连接 执行 自动 调整 功 


全 已 
有 ! 


那么 ， 这 个 功能 到 压 是 怎样 起 作用 的 呢 ? 举 个 例子 ， 请 看 下 面 的 
缓存 上 限 配 置 : 


net.ipv4.tcp_rmem = 8192 87380 16777216 
net.ipv4.tcp wmem = 8192 65536 16777216 
net.ipv4.tcp_ mem = 8388608 12582912 16777216 


tcp_rmem[3] 数 组 表示 任何 一 个 TCP 连 接 上 的 读 缓存 上 限 ， 其 中 
tcp_rmem[0] 表 示 最 小 上 限 ，tcp_rmem[1] 表 示 初 始 上 限 (注意 ， 它 会 覆 
盖 适 用 于 所 有 协议 的 rmem_default 配 置 ) ，tcp_rmem[2] 表 示 最 大 上 限 。 
tcp_wmem[3] 数 组 表示 写 缓存 ， 与 trp_rmem[3] 类 似 。 


tcp_mem[3] 数 组 焉 用 来 设 定 TCP 内 存 的 整体 使 用 状况 ， 所 以 它 的 值 
很 大 〈 它 的 单位 也 不 是 字 节 ， 而 是 页 一 一 4KB 或 者 8KB 等 这 样 的 单 
位 ! ) 。 这 3 个 值 定义 了 TCP 整 体内 存 的 无 压力 值 、 压 力 模式 开启 闭 
值 、 最 大 使 用 值 。 以 这 3 个 值 为 标记 点 则 内 存 共有 4 种 情况 (如 图 9-11 所 


A 


1) 当 TCP 整 体内 存 小 于 tcp_mem[0] 时 ， 表 示 系 统 内 存 总 体 无 压 
力 。 帮 之 前 闪存 曾 经 超过 了 tcp_mem[1] 使 系统 进入 内 存 压力 模式 ， 那 
么 此 时 也 会 把 压力 模式 关闭。 此 时 ， 只 要 TCP 连 接 使 用 的 缓存 没有 达到 
上 限 ， 那 么 新 内 存 的 分 配 一 定 是 成 功 的 。 


2) 当 TCP 内 存在 tcp_mem[0] 与 tcp_mem[1] 之 间 时 ， 系 统 可 能 处 于 
内 存 压 力 模式 ， 例 如 总 内 存 刚 从 tcp_mem[1] 之 上 下 来 ; 也 可 能 是 在 非 
压力 模式 下 ， 例 如 总 内 存 刚 从 tcp_mem[0] 以 下 上 来 。 


此 时 ， 无 论 是 否 在 压力 模式 下 ， 只 要 TCP 连 接 所 用 缓存 未 超过 
tcp_rmem[0] 或 者 tcp_wmem[0]， 那 么 都 一 定 能 成 功 分 配 新 内 存 。 人 否则 ， 


基本 上 就 会 面临 分 配 失败 的 状况 。 (还 有 少量 例外 场景 允许 分 配 内 存 
成 功 ， 这 里 不 纠结 内 核 的 实现 细节 ， 故 略 过 。) 


3) 当 TCP 内 存在 tcp_mem[1] 与 tcp_mem[2] 之 间 时 ， 系 统一 定 处 于 
系统 压力 模式 下 。 行 为 与 情况 2 相同 。 


4) 当 TCP 内 存在 tcp_mem[2] 之 上 时 ， 所 有 的 新 TCP 缓 存 分 配 都 会 
失败 。 


连接 已 用 缓存 是 否 超过 缓存 上 限 ? 


[未 超过 ] 


TCP 总 内 存 是 否 小 于 tcp_mem[0]? 


分 配 缓存 成 功 


分 配 缓存 失败 


图 9-11 Linux 下 TCP 缓 存 上 限 的 目 适 应 调整 


9.11 ”小结 


本 草 在 具体 的 事件 驱动 模块 基础 上 以 epoll 方 式 为 例 ， 完 整地 阐述 
了 Nginx 的 事件 驱动 机 制 ， 并 介绍 了 3 个 与 事件 驱动 密切 相关 的 Nginx 模 
块 ， 同 时 说 明了 事件 驱动 中 的 流程 是 如 何 执行 的 。 男 外 ， 还 介绍 了 
Nginx 在 高 并 发 服务 絮 设 计 上 的 一 些 拉 巧 ， 这 不 仅 对 我 们 了 解 Nginx 的 
架构 有 所 帮助 ， 更 对 我 们 以 后 设计 独立 的 高 性 能 服务 器 有 非常 大 的 局 
发 意义 。 本 草 内 容 也 是 Nginx 其 他 模块 的 基础 ， 之 后 的 章节 都 是 在 讨论 
事件 消费 模块 ， 特 别 是 后 续 的 HTTP 模 块 ， 在 学 习 它 们 的 设计 方法 时 我 
们 会 经 党 性 地 返回 到 本 章 的 事件 续 动机 制 中 。 


第 10 章 ”HTTP 框架 的 初始 化 


从 本 章 开 始 将 探讨 事件 消费 模块 的 “大 户 " 一 一 HTTP 模 块 。Nginx 
作为 Web 服 务 器 ， 其 HTTP 模块 的 数量 远 超过 了 其 他 4 类 模块 (核心 模 
块 、 事 件 模块 、 配 置 模块 、 邮 件 模块 ) ， 其 代码 规模 也 同样 遥遥 领 
“ 


这 些 实现 了 丰富 多 样 功能 的 HTTP 模块 是 以 一 种 什么 样 的 方式 组 织 
起 来 的 呢 ? 它们 各 上 自 功能 的 高 度 可 定制 性 是 如 何 实现 的 ? 共性 在 哪 
里 ? Nginx 又 是 怎样 把 这 些 共性 的 内 容 提取 出 来 ， 并 以 一 个 强大 的 
HTTP 框 架 帮 助 各 个 HTTP 模 块 实现 具体 的 功能 呢 ? 


在 回答 这 些 问 题 前 ， 移 来 回顾 一 下 本 书 的 第 二 部 分 ， 因 为 第 二 部 
分 始终 在 讲 如 何 开 发 一 个 HTTP 模 块 ， 这 种 应 用 级 别 的 HTTP 模 块 就 是 
由 HTTP 框架 定义 和 管理 的 。HTTP 框 架 大 致 由 1 个 核心 模块 

(ngx_http_module) 、 两 个 HTTP 模 块 (ngx_http_core_module、 
ngx_http_upstream_module) 组 成 ， 它 将 负责 调度 其 他 HTTP 模 块 来 一 
起 处 理 用 户 请 求 。 下 面 完 来 弄 清楚 普通 的 HTTP 模 块 和 HTTP 框 架 各 目 
的 关注 点 在 哪里 。 


先 来 看 第 3 章 ~ 第 5 章 例子 中 的 HITP 模 块 通常 会 做 哪些 工作 : 


1) 处 理 已 经 解析 完毕 的 HTTP 请 求 〈 也 就 是 第 二 部 分 中 反复 提 到 
的 填充 好 的 ngx_http_request_t 结 构 体 ) 。 


2) 获取 到 nginx.conf 里 自己 感 兴趣 的 配置 项 ， 无 论 它们 是 否 同时 
出 现在 不 同 的 http{} 配 置 块 、server{} 配 置 块 或 者 location{} 配 置 块 下 ， 
都 需要 正确 地 解析 出 ， 以 此 决定 针对 不 同 的 用 户 请 求 定 制 不 同 的 功 


分 已 
BE °? 


3) 调用 HTTP 框 架 提 供 的 方法 就 可 以 发 送 HTTP 啊 应 ， 包 括 使 用 磁 
盘 IO 读 取 数 据 并 发 送 。 


4) 将 一 个 请 求 分 为 顺序 性 的 多 个 处 理 阶段 ， 前 一 个 阶段 的 结果 会 
影响 后 一 个 阶段 的 处 理 。 例 如 ，ngx_http_access_module 模 块根 据 IP 信 
轧 拒 绝 一 个 用 户 请 求 后 ， 本 应 接着 执行 的 其 他 HITP 模 块 将 没有 机 会 再 
处 理 这 个 请 求 。 


5) 异步 接收 HTTP 请 求 中 的 包 体 ， 可 以 将 网 络 数据 保存 到 磁盘 
和 


6) 异步 访问 第 三 方 服务 。 


7) 分 解 出 多 个 子 请 求 来 构造 处 理 复杂 业务 的 能 力 ， 子 请 求 间 的 处 
理 仍然 是 异步 化 、 非 阻塞 的 。 


以 上 只 是 一 个 简单 粗略 的 总 结 ，HTTP 模 块 或 多 或 少 都 会 需要 这 些 
功能 。 以 这 些 功能 为 例 ， 我 们 来 探讨 一 下 HTTP 框 架 至 少 要 完成 哪些 基 
础 性 的 工作 。 


1) 处 理 所 有 http{} 块 内 的 配置 项 ， 管 理 每 个 HTTP 模 块 感 兴趣 的 配 
置 项 (允许 同一 个 http{} 下 出 现 多 个 server{}、1location{} 等 子 配 置 块 ， 
允许 同名 的 配置 项 同时 出 现在 各 种 配置 块 中 ) 。 


2) HTTP 框 腑 要 能 够 使 用 第 9 章 介绍 的 事件 模块 监听 Web 端 口 ， 并 
处 理 新 连接 事件 、 可 读 事件 、 可 写 事件 等 。 


3) HTTP 框 架 和 需要 有 状态 机 来 分 析 接 收 到 的 TCP 字 符 流 是 否 是 完 


整 的 HTTP 包 。 


4) HITP 框 架 能 够 根据 接收 到 的 HTTP 请 求 中 的 URI 和 HITP 头 
部 ， 并 以 nginx.conf 中 server_name 和 ]location 等 配置 项 为 依据 ， 将 请 求 
按照 其 所 在 阶段 准确 地 分 发 到 某 一 个 HITP 模 块 ， 从 而 调用 它 的 回调 方 
法 来 处 理 该 请 求 。 


5) 向 HTTP 模 块 提供 必要 的 工具 方法 ， 可 以 处 理 网 络 W/O ( 读 取 
HTTP 包 体 、 发 送 HTTP 响 应 ) 和 磁盘 IO 。 


6) 提供 upstream 机 制 帮助 HTTP 模 块 访问 第 三 方 服务 。 


7) 提供 subrequest 机 制 帮助 HTTP 模 块 实现 子 请 求 。 


HTTP 框 以 需要 做 的 工作 很 多 ， 实 际 上 ，HTTP 的 框 杂 性 代码 也 是 
极为 庞大 的 ， 为 了 人 商 便 起 见 ， 本 书 以 后 的 章节 将 专注 在 HTTP 框 以 的 流 
程 代 码 中 ， 完 全 不 会 涉及 具体 的 HITP 功 能 模块 ， 也 不 会 涉及 框架 中 不 
太 重 要 的 工具 性 的 代码 。 


本 章 会 完整 地 介绍 ngx_http_module 模 块 ， 其 中 涉及 少量 
ngx_http_core_module 模 块 的 功能 。 因 为 构成 HITP 框 架 的 几 个 模块 间 
的 代码 耦合 性 很 高 ， 所 以 对 于 HTTP 框 架 的 介绍 并 不 会 按照 模块 进行 ， 
而 是 从 HTTP 框 架 的 功能 和 架构 上 进行 ， 其 中 本 章 介绍 Nginx 启 动 过 程 
中 HTTP 框 架 是 怎样 初始 化 的 ， 第 11 章 介绍 Nginx 运 行 过 程 中 HTTP 框 架 
是 怎样 调度 HTTP 模块 处 理 请 求 的 ， 第 12 章 讲述 访问 第 三 方 服 务 的 
upstream 机 制定 如 何 工 作 的 。 


10.1 HTTP 框架 概述 


为 了 让 读者 对 HTTP 框 架 所 要 完成 的 工作 有 一 个 直观 的 认识 ， 本 章 
将 依托 一 个 贯穿 始终 的 nginx.conf 配 置 范 例 来 说 明 框 架 的 行为 ， 如 下 所 


修 ° 
http { 
mytest_num 1; 
server { 


server_name A; 

listen 127.0.0.1:8000; 

listen 80; 

mytest_num 2; 

location /Li1 { 
mytest_num 3， 


location /L2 { 
mytest_num 4; 


} 


server { 
server_name B; 
listen 80; 
listen 8080; 
listen 173.39.160.51:8000; 
mytest_num 5; 
location /Li1 { 
mytest_num 6; 


} 
location /L3 { 
mytest_num 7; 


从 上 面 这 个 简单 的 例子 中 ， 可 以 获取 下 列 信息 : 


HTTP 框架 是 文 持 在 http{} 块 内 拥有 多 个 server{}、location{} 配 置 
块 的 。 


:选择 使 用 哪 一 个 server 虚 拟 主机 块 是 取决 于 server_name 的 。 


.任意 的 server 块 内 都 可 以 用 listen 来 监听 端口 ， 在 不 同 的 server 块 内 
人 允许 监听 相同 的 端口 。 


选择 使 用 哪 一 个 location 块 是 将 用 户 请 求 URI 与 合适 的 server 块 内 
的 所 有 location 表 达 式 做 匹配 后 决定 的 。 


:同一 个 配置 项 可 以 出 现在 任意 的 http{}、server{}、location{} 等 配 
置 块 中 。 


HTTP 框 架 如 何 实 现 上 述 的 配置 项 特性 呢 ? 


HTTP 框 架 的 首要 任务 是 通过 调用 ngx_http_module _t 接 口中 的 方法 
来 管理 所 有 HTTP 模 块 的 配置 项 ，10.2 节 中 会 详细 描述 这 一 过 程 。 在 
10.3 节 中 ， 我 们 会 探讨 监听 端口 与 server 虚 拟 主 机 间 的 关系 ， 包 括 它们 
是 用 何 种 数据 结构 关联 在 一 起 的 。 所 有 的 server 虚 拟 主 机 会 以 散 列 表 的 
数据 结构 组 织 起 来 ， 以 达到 高 效 查询 的 目的 ， 在 10.4 节 中 会 介绍 这 一 
过 程 。 所 有 的 location 表 达 式 会 以 一 个 静态 的 二 又 查找 树 组 织 起 来 ， 以 
达到 高 效 查 询 的 目的 ， 在 10.5 节 中 会 说 明 它 。 对 于 每 一 个 HTTP 请 求 ， 


都 会 以 流水 线形 式 划 分 为 多 个 阶段 ， 以 供 HTTP 模 块 插 入 到 HTTP 框 架 
中 来 共同 处 理 请 求 ，10.6 节 中 会 说 明 这 些 阶段 划分 、 实 现 的 依据 所 
在 。 在 10.7 广 中， 将 会 完整 地 说 明 在 Nginx 局 动 过 程 中 ，HTTP 框 架 是 
如 何 初 始 化 的 。 


下 面 开始 介绍 ngx_http_module_t 接 口 的 相关 内 容 。 


ngx_http_module 核 心 模块 定义 了 新 的 模块 类 型 
NGX_HTTP_MODULE。 这 样 的 HTTP 模 块 对 于 ctx 上 下 文 使 用 了 不 同 
于 核心 模块 、 事 件 模块 的 新 接口 ngx_http_module t， 虽 然 第 3 章 中 曾经 
提 到 过 ngx_http_module _t 接 口 的 定义 ， 但 那 时 我 们 介绍 的 角度 是 如 何 
开发 一 个 HTTP 模 块 ， 现 在 探讨 实现 HTTP 框 架 时 ， 对 
ngx_http_module_t 接 口 的 解读 就 不 同 了 。 在 重新 解读 
ngx_http_module t 接 口 之 前 ， 先 对 不 同 级 别 的 HTTP 配 置 项 做 个 缩写 名 
词 的 定义 : 


:直接 隶属 于 http{} 块 内 的 配置 项 称 为 main 配 置 项 。 
.直接 隶属 于 server{} 块 内 的 配置 项 称 为 srv 配 置 项 。 
.直接 隶属 于 location{f} 抉 内 的 配置 项 称 为 loc 配 置 项 。 


其 他 配置 块 本 草 不 会 涉及 ， 因 为 它们 与 HTTP 框架 没有 任何 关系 。 


对 于 每 一 个 HTTP 模块 ， 都 必须 实现 ngx_http_module_{t 接 口 。 下 面 
将 从 HTTP 框 桨 的 角度 来 进行 重新 解读 ， 如 下 所 示 。 


typedef struct { 
// 在 解析 


http{..,.} 内 的 配置 项 前 回调 


ngx_int_t (*preconfiguration)(ngx_conf_t *cf)， 


// 解析 完 
http{.,.} 内 的 所 有 配置 项 后 回调 


ngx_int_t (*postconfiguration)(ngx_conf_t *cf); 


/* 创 建 用 于 存储 
HTTP 全 局 配置 项 的 结构 体 ， 该 结构 体 中 的 成 员 将 保存 直属 于 
httpf{f} 块 的 配置 项 参数 。 它 会 在 解析 


main 配 置 项 前 调 


*/ 
void *(*create main conf)(ngx_conf_t *cf); 
// 解析 完 


main 配 置 项 后 回调 


char *(*init_main_conf)(ngx_conf t *cf, void *conf ) ， 
/* 创 建 用 于 存储 可 同时 出 现在 


main、 
srv 级 别 配置 项 的 结构 体 ， 该 结构 体 中 的 成 员 与 
server 配 置 是 相关 联 的 


void *(*create srv_conf)(ngx_conf_t *cf); 


/*create_srv_conf 产生 的 结构 体 所 要 解析 的 配置 项 ， 可 能 同时 出 现在 


main、 


srv 级 别 中 ， 


merge_srv_conf 方 法 可 以 把 出 现在 


main 级 别 中 的 配置 项 值 合并 到 


srv 级 别 配 置 项 中 


eh 
char *(*merge_srv_conf)(ngx_conf_t *cf, void *prev, void *conf); 


/* 创 建 用 于 存储 可 同时 出 现在 


loc 级 别 配 置 项 的 结构 体 ， 该 结构 体 中 的 成 员 与 
location 配 置 是 相关 联 的 


*/ 
void *(*create loc conf)(ngx_conf_t *cf); 


/*create_loc_conf 产 生 的 结构 体 所 要 解析 的 配置 项 ， 可 能 同时 出 现在 


main、 
srv、 


loc 级 别 中 ， 


merge_loc_conf 方 法 可 以 分 别 把 出 现在 


main、 


srv 级 别 的 配置 项 值 合并 到 


loc 级 别 的 配置 项 中 


*/ 
char *(*merge_loc conf)(ngx_conf_t *cf, void *prev, void *conf); 
} ngx_http_module _t; 


可 以 看 到 ，ngx_http_module_t 接 口 完全 是 围绕 着 配置 项 来 进行 
的 ， 这 与 第 8 章 提 到 过 的 可 定制 性 、 可 扩展 性 等 染 构 特性 是 一 怪 的 。 
一 个 HTTP 模 块 都 将 根据 main、srv、loc 这 些 不 同 级别 的 配置 项 来 决定 
目 己 的 行为 。 


10.2 ”管理 HTTP 模 块 的 配置 项 


上 文 介绍 过 事件 配置 项 的 管理 ， 其 实 HTTP 配 置 项 的 管理 与 事件 模 
块 有 些 相似 ， 但 由 于 它 具 有 3 种 不 同 级 别 配 置 项 ， 所 以 管理 要 复杂 许 
多 。 对 于 HTTP 模 块 而 言 ， 只 需 关 心 工 作 时 能 够 取 到 正确 的 配置 项 。 但 
对 于 HTTP 框 架 而 言 ， 任 何 一 个 HTTP 模 块 的 server 相 关 的 配置 项 都 是 可 
能 出 现在 main 级 别 中 ， 而 location 相 关 的 配置 项 可 能 出 现在 main、srv 级 
别 中 。 而 server 十 可 能 存在 许多 个 的 ，location 更 是 可 以 有 反复 舱 套 的 ， 这 
样 就 要 为 每 个 HTTP 模 块 按照 nginx.conf 里 的 配置 块 建立 许多 份 配置 。 在 
10.1 节 的 例子 中 ， 共 出 现 了 7 个 配置 块 ， 对 于 HTTP 框架 而 言 ， 就 需要 为 
所 有 的 HTTP 模块 分 配 7 个 用 于 存储 配置 结构 体 指针 的 数组 。 


在 处 理 http{f} 块 内 的 main 级 别 配置 项 时 ， 对 每 个 HTTP 模块 来 说 ， 
都 会 调用 create_main_conf、create_srv_conf、create_loc_conf 方 法 建立 3 
个 结构 体 ， 分 别 用 于 存储 HTTP 全 局 配置 项 、server 配 置 项 、location 配 
置 项 。 现 在 问题 来 了 ，http{} 内 的 配置 项 明明 束 是 main 级 别 的 ， 有 了 
create_main_conf 生 成 的 结构 体 已 经 足够 保存 全 局 配置 项 参数 了 ， 为 什 
么 还 要 调用 create_srv_conf、create_loc_conf 方 法 建立 结构 体 呢 ? 其 实 ， 
这 是 为 了 把 同时 出 现在 http{}、server{}、location{} 内 的 相同 配置 项 进 
行 合 并 而 做 的 准备 。 假 设 有 一 个 与 server 相 关 的 配置 项 (例如 负 员 指定 
每 个 TCP 连 接 上 内 存 池 大 小 的 connection_pool_size 配 置 项 ) 同时 出 现在 


http{}、 server{} 中 ， 那 么 对 它 感 兴趣 的 HITP 模 块 就 有 权 决 定 srv 结 构 体 
内 的 成 员 完 竟 是 以 main 级 别 配 置 项 为 准 ， 还 是 srv 级 别 配置 项 为 准 。 结 
合 10.1 太 的 例子 来 看 ，mytest_num 出 现在 http{} 下 时 参数 为 1， 出 现在 
server A{} 下 时 参数 为 2， 那 么 ，mytest 模 块 就 有 权 决 定 ， 当 处 理 server 
A 虚拟 主机 时 ， 究 况 是 把 mytest_num 参 数 当 做 1 还 是 2， 或 者 把 它们 俩 相 
加 ， 这 都 是 任何 一 个 HTTP 模 块 的 目 由 。 对 于 HTTP 框 架 而 言 ， 在 解析 
main 级 别 的 配置 项 时 ， 必 须 同时 创建 3 个 结构 体 ， 用 于 合并 之 后 会 解析 
到 的 server、location 相 关 的 配置 项 。 


对 于 server{} 块 内 配置 项 的 处 理 ， 需 要 调用 每 个 HTTP 模 块 的 
create_srv_conf 方 法 、create_loc_conf 方 法 建立 两 个 结构 体 ， 分 别 用 于 存 
储 server、location 相 天 的 配置 项 ， 其 中 create_ loc_conf 产 生 的 结构 体 仅 
用 于 合并 location 相 关 的 配置 项 。 


对 于 location 块 内 配置 项 的 处 理 则 简单 许多 ， 只 需要 调用 每 个 HTTP 
模块 的 create_loc_conf 方 法 建立 1 个 结构 体 即 可 。 


结合 10.1 广 中 nginx.conf 配 置 文件 的 片断 来 看 ， 实 际 上 HTTP 框 架 最 
多 必须 为 一 个 HTTP 模 块 (如 mytest 模 块 ) 创建 3+2+1+1+2+1+1=11 个 配 
置 结构 体 ， 而 经 过 合并 后 实际 上 每 个 HTTP 模 块 会 用 到 的 结构 体 有 7 
个 。 可 为 什么 mytest 模 块 使 用 ngx_http_mytest_conf t 结 构 体 时 好 像 只 有 
1 个 配置 结构 体 呢 ? 因为 在 HITP 框 架 处 理 到 某 个 阶段 时 ， 例 如 ， 在 寻 
找到 适合 的 location 前 ， 如 果 试 图 去 取 ngx_http_mytest_conf t 结 构 体 ， 


得 到 的 将 是 srv 级 别 下 的 配置 ， 而 寻找 到 location 后 ， 
ngx_http_mytest_conf t 结 构 体 中 的 成 员 将 是 loc 级 别 下 的 配置 。 


下 面 介 绍 一 下 ngx_http_module 模 块 在 实现 上 是 如 何 体现 上 述 思 路 
的 。 


10.2.1 管理 main 级 别 下 的 配置 项 


上 文 说 过 ， 在 解析 HTTP 模 块 定义 的 main 级 别 配 置 项 时 ， 将 会 分 别 
调用 每 个 HTTP 模 块 的 create_main _conf 、create_srv_conf 、 
create_loc_conf 方 法 建立 3 个 结构 体 ， 分 别 用 于 存储 全 局 、server 相 关 
的 、location 相 关 的 配置 项 ， 但 它们 冤 竟 是 以 何 种 数据 结构 保存 的 呢 ? 
与 核心 结构 体 ngx_cycle_t 中 的 conf_ctx 指 针 义 有 什么 样 的 关系 呢 ? 在 图 
10-10 中 的 第 2 步 ~ 第 7 步 包 含 了 解析 main 级 别 配置 项 的 所 有 流程 ， 而 图 
10-1 将 会 展现 它们 在 内 存 中 的 布局 ， 可 以 看 到 ， 其 中 
ngx_http_core_ module 模 块 完成 了 HTTP 框 架 的 大 部 分 功能 ， 而 它 又 是 第 
1 个 HITP 模 块 ， 因 此 ， 它 使 用 到 的 3 个 结构 体 

(ngx_http_core_main_conf t、 ngx_http_core_srv_conf t、 


ngx_http_core_loc_conf t) 也 是 用 户 非常 关心 的 。 


图 10-1 中 有 一 个 结构 体 叫 做 ngx_http_conf_ctx_t， 它 是 HTTP 框 架 中 
一 个 经 常用 到 的 数据 结构 ， 下 面 看 看 它 的 定义 。 


typedef struct { 
/* 指 向 一 个 指针 数组 ， 数 组 中 的 每 个 成 员 都 是 由 所 有 


HTTP 模 块 的 


create_main_conf 方 法 创建 的 存放 全 局 配置 项 的 结构 体 ， 它 们 存放 着 解析 


http{} 块 内 的 
main 级 别 的 配置 项 参数 
A 


void **main_conf,; 


/* 指 向 一 个 指针 数组 ， 数 组 中 的 每 个 成 员 都 是 由 所 有 
HTTP 模 块 的 


create_srv_conf 方 法 创建 的 与 
server 相 关 的 结构 体 ， 它 们 或 存放 
main 级 别 配 置 项 ， 或 存放 
srv 级 别 配 置 项 ， 这 与 当前 的 


ngx_http_conf_ctx_t 是 在 解析 


http 人 {或 者 
server{} 块 时 创建 的 有 关 


A 

void **srv_conf; 

/* 指 向 一 个 指针 数组 ， 数 组 中 的 每 个 成 员 都 是 由 所 有 
HTTP 模 块 的 
create_1oc_conf 方 法 创建 的 与 


location 相 关 的 结构 体 ， 它 们 可 能 存放 着 


main、 
Srv、 


loc 级 别 的 配置 项 ， 这 与 当前 的 


ngx_http_conf_ctx_t 是 在 解析 


http{}、 


server{} 或 


location{} 块 时 创建 的 有 关 


*/ 
void **]loc_conf; 
} ngx_http_conf_ctx_t; 


ngx_http_conf_ctx_t 中 仅 有 3 个 成 员 ， 它 们 分 别 指 同 3 个 指针 数组 。 
在 10.2.4 广 中 ， 读 者 会 看 到 srv_conf 数 组 和 ]oc_conf 数 组 在 配置 项 的 合并 
操作 中 是 如 何 使 用 的 。 


在 核心 结构 体 ngx_cycle_t 的 conf_ctx 成 员 指 向 的 指针 数组 中 ， 第 7 个 
指针 由 ngx_http_module 模 块 使 用 (ngx_http_module 模 块 的 index 序 号 为 
6， 由 于 由 0 开始 ， 所 以 它 在 ngx_modules 数 组 中 排行 第 7。 在 存放 全 局 
配置 结构 体 的 conf_ctx 数 组 中 ， 第 7 个 成 员 指 向 ngx_http_module 模 
块 ) ， 这 个 指针 设置 为 指向 解析 http{} 块 时 生成 的 ngx_http_conf_ctx_t 结 
构 体 ， 而 ngx_http_conf_ctx_t 的 3 个 成 员 则 分 别 指向 新 分 配 的 3 个 指针 数 
组 。 新 的 指针 数组 中 成 员 的 意义 由 每 个 HTTP 模 块 的 ctx_index 序 号 指定 

(ctx_index 在 HITP 模 块 中 表明 它 处 于 HITP 模 块 间 的 序号 ) ， 例 如 ， 
第 6 个 HTTP 模 块 的 ctx_index 是 5 (ctx_index 同 样 由 0 开始 计数 ) ， 那 么 
在 ngx_http_conf_ctx_t 的 3 个 数组 中 ， 第 6 个 成 员 束 指 疝 第 6 个 HTTP 模 块 
的 create_main_conf、create_srv_conf、create_loc_con{ 方 法 建立 的 结构 


体 ， 当 然 ， 如 采 相 应 的 回调 方法 没有 实现 ， 该 指针 就 为 NULL 空 指 守 。 


ngx_cycle_t 


所 有 核心 模块 的 配置 结构 体 指 针 


ei 
[| 
ee 


一 再 ngx_modules 数 组 可 以 看 出 ， 第 7 个 模块 是 
ngx_http_module 模 块 ，conf_ctx 数 组 中 第 7 位 存储 
着 Ngx_http_module 模 块 的 配置 项 指针 ， 在 这 里 ， 
这 个 指针 被 定义 为 指向 ngx_http_conf_ctx_t 结 构 体 


conf_ctx 


ngx_http_conf_ctx_t 结 构 体 


EX 


a ngx_http_core_main_conf_t 


A 志 


EL 
= == 


create_main _conf 


生成 的 结构 体 指针 


面 醒 面 画 面 柄 本 
和 


create_srv_conf 


生成 的 结构 体 指 针 


国 国 村 轩 轩 本 夺 第 6 个 HTTP 模 块 create_main_conf_t 结 构 体 


create_loc_conf 


生成 的 结构 体 指针 


ngx_ht tp_co re_srv_conf { 


ngx_http_core_loc_conf_t 


第 6 个 HTTP 模 块 create_srv_conf {结构 体 


第 6 个 HTTP 模 块 create_loc_conf _t 结 构 体 


图 10-1 HTTP 框 架 解 析 main 级 别 配置 项 时 配置 结构 体 的 内 存 示 意图 


ngx_http_core_module 模 块 是 第 1 个 HTTP 模 块 ， 它 的 ctx_index 序 号 
是 0， 因 此 ， 数 组 中 的 第 1 个 指针 将 指 癌 ngx_http_core_module 模 块 生成 


的 ngx_http_core_main_conf t、 ngx_ http_core_srv_conf t、 


ngx_http_core_loc_conf t 结 构 体 。 


可 如 何 由 ngx_cycle_t 核 心 结构 体 中 找到 main 级 别 的 配置 结构 体 
呢 ? Nginx 提 供 的 ngx_http_cycle_get_module_main_conf 宏 可 以 实现 这 个 
功能 ， 如 下 所 示 。 


#define ngx_http_cycle get module main conf(cycle, module) \ 
(cycle->conf_ctx[ngx_http_module.index] \ 
((ngx_http_conf_ctx_t *) 
cycle->conf_ctx[ngx_http_module.index]) 
->main_conf[module.ctx_index]: \ 
NULL) 


其 中 参数 cycle 是 ngx_cycle_t 核 心 结构 体 指 针 ， 而 module 则 是 所 要 
操作 的 HITP 模 块 。 它 的 实现 很 简单 ， 先 由 cycle 的 conf _ctx 指 针 数 组 中 
找到 ngx_http_module.index 序 号 (上 文 说 过 ， 其 index 为 6) 对 应 的 指 
针 ， 获 取 到 http{} 块 下 的 ngx_http_conf_ctx_t 成 员 ， 然 后 经 由 main_conf 
数组 即 可 找到 所 有 HTTP 模 块 的 main 级 别 配置 结构 体 。 最 后 ， 根 据 所 要 
查询 的 module 数 组 的 ctx_index 序 号 取得 其 main 级 别 下 的 配置 结构 体 ， 
例如 : 


ngx_http_perl main conf_t *pmcf = ngx_http_cycle get module main conf(cycle, 
ngx_http_perl module); 


@ 注意 HTTP 全 局 配置 项 是 基础 ， 管 理 server、location 等 配置 
块 时 取决 于 ngx_http_core_module 模 块 出 现在 main 级 别 下 存储 全 局 配置 


项 的 ngx_http_core_main_conf t 结 构 体 。 
10.2.2 ”管理 server 级 别 下 的 配置 项 


在 解析 main 级 别 配置 项 时 ， 如 果 发 现 了 server{} 配 置 项 ， 束 会 回调 
ngx_http_core_server 方 法 (该 方法 属于 ngx_http_core_module 模 块 ) ， 
而 在 这 个 方法 里 则 会 开始 解析 srv 级 别 的 配置 项 ， 其 流程 如 图 10-2 所 


坟 ° 
下 面容 要 说 明 图 10-2 中 的 步骤 : 


1) 在 解析 到 server 块 时 ， 首 先 会 像 解析 http 块 一 样 ， 建 立 属于 这 个 
server 块 的 ngx_http_conf_ctx_{t 结 构 体 。 在 ngx_http_conf_ctx_t 的 3 个 成 员 
中 ，main_conf 将 指 同 所 属 的 http 块 下 ngx_http_conf_ctx_t 结 构 体 的 
main_conf 指 针 数 组 ， 而 srv_conf 和 loc_conf 都 将 重新 分 配 指 针 数 组 ， 数 
组 的 大 小 为 ngx_http_max_module， 也 就 是 所 有 HTTP 模 块 的 总 数 。 


2) 循环 调用 所 有 HTTP 模 块 的 create_srv_conf 方 法 ， 将 返回 的 结构 
体 指针 按照 模块 序号 ctx_index 保 存 到 上 述 的 srv_conf 指 针 数 组 中 。 


3) 循环 调用 所 有 HTTP 模 块 的 create_ loc_conf 方 法 ， 将 返回 的 结构 
体 指针 按照 模块 序号 ctx_index 保 存 到 上 述 的 loc_conf 指 针 数 组 中 。 


4) 第 1 个 HTTP 模 块 就 是 ngx_http_core_module 模 块 ， 它 在 
create_srv_conf 方 法 中 将 会 生成 非常 天 键 的 ngx_http_core_srv_conf_t 配 
置 结构 体 ， 这 个 结构 体 对 应 着 当前 正在 解析 的 server 块 ， 这 时 ， 将 
ngx_http_core_srv_conf t 深 加 a 到 全 局 的 ngx_http_core_main_conf t 结 构 体 
的 servers 动 态 数 组 中 ， 在 图 10-3 中 会 看 到 这 一 点 。 


1 ) 分 配 存 放 srv 级 别 配 置 项 指针 的 
两 个 数组 


2 ) 调用 所 有 HTTP 模 块 的 


create _srv_conf 方法 


3) 调用 所 有 HTIP 模 块 的 


create loc_conf 方 法 


4) 将 属于 当前 server 块 的 ngx_http _core __SrV_conf 1 
添加 到 servers 动态 数组 中 


5 ) 解析 当前 server 块 下 的 全 部 
srv 级 别 配 置 项 


6 ) 如 果 没 有 listen 选项 ， 则 监听 
默认 的 80 端 口 


人 


图 10-2 ”解析 server{} 块 内 配置 项 的 流程 


5) 解析 当前 server{} 块 内 的 所 有 配置 项 。 


6) 如 果 在 server{} 块 内 没有 解析 到 listen 配 置 项 ， 则 意味 着 当前 的 
server 虚 拟 主机 并 没有 监听 TCP 端 口 ， 这 不 符合 HTTP 框 架 的 设计 原则 。 
于 是 将 开始 监听 默认 端口 80， 实 际 上 ， 如 果 当 前 进程 没有 权限 监听 
1024 以 下 的 问 口 ， 则 会 改 为 监听 8000 问 口 。 


由 于 http 块 只 有 1 个 ， 因 此 在 10.2.1 节 中 可 以 简单 地 给 出 main 级 别 配 
置 项 的 内 存 示意 图 。 但 http 块 内 会 包含 任意 个 server 块 ， 对 于 每 个 server 
块 都 需要 建立 1 个 ngx_http_conf_ctx_t 结 构 体 ， 这 些 server 块 的 
ngx_http_conf_ctx_t 结 构 体 是 通过 ngx_array_t 动 态 数 组 组 织 起 来 的 ， 这 
其 中 的 关系 就 比较 复杂 了 ， 图 10-3 是 它们 简单 的 内 存 示意 图 。 


所 有 核心 模块 的 配置 结构 体 指针 | | 


ngx_http_conf_ctx_t 结 构 体 


- ngx_http_core_main_conf_t 
main_conf loc _conf 


http 块 下 create_main_conf 配置 项 指针 


| 


servers 数 组 中 指针 皆 指 回 属于 server A 块 


ngx_http _core _srv _conf 上 


server A 块 下 


ngx_ http_conf ctx_r 结构 体 


ngx_http_core_srv_conf_+ 


| || 


~ 一 
server A 块 下 各 模块 
create_srv_conf 生成 的 结构 体 指 针 


加 国 林 本 曙 夯 柄 加 丁 醒 
TS 


server A 块 下 各 模块 
create_loc_conf 生 成 的 结构 体 指 针 


ngx_h ttp_core_srv_con :对 


server B 块 下 ngx_http_conf_ctx_t 结 构 体 


图 10-3 ” HTTP 模块 srv 级 别 配置 项 结构 体 指针 的 内 存 示 意图 


图 10-3 是 针对 10.1 市 中 的 例子 所 画 的 示意 图 ， 在 http 块 下 有 两 个 
server 块 ， 分 别 表示 虚拟 主机 名 为 A 的 配置 块 和 虚拟 主机 名 为 B 的 配置 
块 。 解 析 每 一 个 server 块 时 都 会 创建 一 个 新 的 ngx_http_conf_ctx_t 结 构 
体 ， 其 中 的 main_conf 将 指 同 http 块 下 main_conf 指 针 数 组 ， 而 srv_conf 和 
loc_conf 数 组 则 都 会 重 刹 分配 ， 它 们 的 内 容 就 是 所 有 HTTP 模 块 的 
create_srv_conf 方 法 、create_loc_conf 方 法 创建 的 结构 体 指针 。 


在 10.2.1 广 中 提 到 的 main 级 别 配 置 项 中 ，ngx_http_core_module 模 块 
的 ngx_http_core_main_conf t 结 构 体 中 有 一 个 servers 动 态 数 组 ， 如 下 所 


修 ° 


typedef struct { 
/* 存 储 指针 的 动态 数组 ， 每 个 指针 指向 


ngx_http_core_srv_conf_t 结 构 体 的 地 址 ， 也 就 是 其 成 员 类 型 为 


ngx_http_core_srv_conf_t** */ 
ngx_array_t servers; 


} ngx_http_core_main_conf tt， 


servers 动 态 数 组 中 的 每 一 个 元 素 都 是 一 个 指针 ， 它 指向 用 于 表示 
server 块 的 ngx_http_core_srv_conf t 结 构 体 的 地 址 (属于 
ngx_http_core_module 模 块 ) 。ngx_http_core_srv_conf t 结 构 体 中 有 1 个 
ctx 指 秆 ， 它 指向 解析 server 块 时 新 生成 的 ngx_http_conf_ctx_t 结 构 体 ， 
具体 如 下 所 示 。 


typedef struct { 
// 指向 当前 


server 块 所 属 的 


ngx_http_conf_ctx_t 结 构 体 


ngx_http_conf_ctx_t *ctx; 
/* 当 前 


server 块 的 虚拟 主机 名 ， 如 果 存 在 的 话 ， 则 会 与 


HTTP 请 求 中 的 


Host 头 部 做 匹配 ， 匹 配 上 后 再 由 当前 


ngx_http_core_srv_conf_t 处 理 请 求 


*/ 
ngx_str_t server_name; 


} ngx_http_core_srv_conf_t; 


这 样 ，server 块 下 以 ngx_http_conf_ctx_t 组 织 起 来 的 所 有 配置 项 结构 
体 ， 就 会 由 servers 动 态 数 组 关联 起 米 。servers 动 态 数 组 中 的 元 素 个 数 与 
http 块 下 的 server 配 置 块 个 数 是 一 致 的 。 


10.2.3 ”管理 location 级 别 下 的 配置 项 


在 解析 srv 级 别 配置 项 时 ， 如 果 发 现 了 location{} 配 置 块 ， 束 会 回调 
ngx_http_core_location 方 法 (该 方法 属于 ngx_http_core_module 模 块 ) ， 
在 这 个 方法 里 则 会 开始 解析 loc 级 别 的 配置 项 ， 其 流程 如 图 10-4 所 示 。 

下 面 简要 介绍 一 下 图 10-4 中 的 流程 : 


1) 在 解析 到 ]ocation{} 配 置 块 时 ， 仍 然 会 像 解析 http 块 一 样 ， 先 建 


Yngx_http_conf_ctx_t 结 构 体 ， 只 是 这 里 的 main_conf 和 srv_conf 都 将 指 


回 所 属 的 server 块 下 ngx_http_conf_ctx_t 结 构 体 的 main_conf 和 srv_conf 指 
针 数 组 ， 而 loc_conf 则 将 指 同 重新 分 配 的 指针 数组 。 


2) 循环 调用 所 有 HTTP 模 块 的 create_ loc_conf 方 法 ， 将 返回 的 结构 
体 指针 按照 模块 序号 ctx_index 保 存 到 上 述 的 loc_conf 指 针 数 组 中 。 


3) 如 果 在 location 中 使 用 了 正则 表达 式 ， 那 么 这 时 将 调用 
pcre_compile 方 法 预 编 译 正则 表达 式 ， 以 提高 性 能 。 


4) 第 1 个 HTTP 模 块 是 ngx_http_core_module 模 块 ， 它 在 
create_loc_conf 方 法 中 将 会 生成 ngx_http_core loc_conf t 配 置 结构 体 ， 
可 以 认为 该 结构 体 对 应 着 当前 解析 的 location 块 。 这 时 会 生成 
ngx_http_location_queue_t 结 构 体 ， 因 为 每 一 个 ngx_http_core loc_conf t 
结构 体 都 对 应 着 1 个 ngx_http_location_queue_t， 因 此 ， 此 处 将 把 
ngx_http_location_queue_t 串 联 成 双亲 链表， 在 图 10-5 中 会 看 到 这 一 点 。 


1 ) 分 配 用 于 存放 loc 级 别 配置 项 指针 的 1 个 数组 


2 ) 调用 所 有 模块 的 create _loc_conf 方法 
| 当前 location 后 的 表达 式 是 否 使 用 正则 表达 式 | 


[没有 使 用 正则 表达 式 ] 
[使 用 了 正则 表达 式 ] 


3 ) 预 编译 正则 表达 式 
4) 建 立 ngx_http location_dqueuet 并 添加 到 双 回 链表 


Sy 解析 当 证 location 下 的 所 有 loc 级 别 配 置 项 


图 10-4 解析 location{f} 配 置 块 的 流程 
5) 解析 当前 location{} 配 置 块 内 的 loc 级 别 配置 项 。 


图 10-5 为 HTTP 模 块 loc 级 别 配置 项 结构 体 指针 的 内 存 示 意图 。 


图 10-5 仍 然 是 依据 10.1 节 中 的 配置 块 例子 所 画 的 示意 图 ， 不 过 
里 仅 涉 及 server 块 A (其 server_name 的 参数 值 为 A) 以 及 它 所 属 的 
location L1 块 。 在 解析 http 块 时 曾 创 建 过 1 个 ngx_http_core_loc_conf t 结 
构 体 ( 见 10.2.1 节 ) ， 在 解析 server 块 A 时 曾经 创建 过 1 个 
ngx_http_core_loc_conf t 结 构 体 ( 见 10.2.2 节 ) ， 而 解析 其 下 的 location 
块 L1 时 也 创建 了 ngx_http_core_loc_conf t 结 构 体 ， 从 图 10-5 中 可 以 看 出 
这 3 个 结构 体 间 的 关系 。 下 面 先 看 看 图 10-5 中 ngx_http_core_loc_conf t 的 
3 个 关键 成 员 : 


typedef struct ngx_http_core_ loc conf_s ngx_http_core_ loc conf_t; 
struct ngx_http_core_loc conf_s { 
// location 的 名 称 ， 即 


nginx.conf 中 


location 后 的 表达 式 


ngx_str_t name; 


/* 指 向 所 属 


location 块 内 


ngx_http_conf_ctx_t 结 构 体 中 的 


loc_conf 指 针 数 组 ， 它 保存 着 当前 


location 块 内 所 有 


HTTP 模 块 


create_loc_conf 方 法 产生 的 结构 体 指针 


*/ 
void **]oc_conf; 
/* 将 同一 个 


server 块 内 多 个 表达 


location 块 的 


ngx_http_core_loc_conf_t 结 构 体 以 双向 链表 方式 组 织 起 来 ， 该 


locations 指 针 将 指向 


ngx_http_location_queue_t 结 构 体 


*/ 
ngx_queue_t *locations; 


}; 


ngx_cycle_t 


所 有 核心 模块 的 配置 结构 体 指针 


conf _ctx 


ngx_http_core_mai n_conf + 


SeITVeTS 


http 块 下 create_main_conf 配置 项 指针 


servers 数 组 中 指针 皆 指 向 
ngx_http _core _srv _conf 上 


server A 块 下 


块 下 ngx_http_core_srv_conf_t 


nf ctx_t 


一- 


~ 
~ 


server A 块 下 create_srv 


_conf 生成 的 结构 体 指针 
|| | | | | | | 
一 ngx_http_core_loc_conf_t 


server A 块 下 create_loc_conf 


生成 的 结构 体 指 针 


本 
location L 1 块 下 ngx_http_conf_ctx_t 结 构 体 


属于 location Ll 块 


a 
| oo_war 
和 


location 上 L 1 块 下 create_loc_conf 生 成 的 结构 体 指针 


图 10-5 ” HTTP 模块 loc 级 别 配 置 项 结构 体 指针 的 内 存 示 意 


loc_conf 


ngx_http_core_loc_conf + 


可 以 这 么 说 ，ngx_http_core_ loc_conf_t 拥 有 足够 的 信息 来 表达 
location 块 ， 它 的 loc_conf 成 员 也 可 以 引用 到 各 HTTP 模 块 在 当前 location 
块 中 的 配置 项 。 所 以 ， 过 某 种 容 姻 将 ngx_http_core_loc_conf t 组 
织 起 来 ， 也 就 是 把 location 级 别 的 配置 项 结构 体 管理 起 来 了 。 但 
ngx_http_core_loc_conf { 又 是 放置 在 什么 样 的 容 历 中 呢 ? 注意 ， 图 10-3 
在 解析 server 块 A 时 有 1 个 ngx_http_core_loc_conf t 结 构 体 ， 它 的 地 位 与 
server 块 A 内 的 各 个 location 块 对 应 的 ngx_http_core_loc_conf t 结 构 体 是 
不 同 的 ，location LI1、location L2 块 内 的 ngx_http_core_loc_conf t 是 通过 
server A 块 内 产生 的 ngx_http_core_loc_conf t 关 联 起 来 的 。 


ee 体 中 有 一 个 成 员 locations， 它 表示 
属于 当前 块 的 所 有 location 块 通过 ngx_http_location_queue t 结 构 体 构成 
的 双 回 链表 ， 如 下 所 示 。 


typedef struct { 
/*queue 将 作为 


ngx_queue_t 双 向 链表 容器 ， 从 而 将 


ngx_http_location_queue_t 结 构 体 连接 起 来 


*/ 
ngx_queue_t queue; 
/* 如 果 


location 中 的 字符 串 可 以 精确 匹配 (包括 正则 表达 式 ) ， 
exact 将 指向 对 应 的 


ngx_http_core_loc_conf_t 结 构 体 ， 否 则 值 为 


NULL*/ 
ngx http core_loc conf_t *exact 
/* 如 果 


location 中 的 字符 串 无 法 精确 匹配 (包括 了 自 定义 的 通配符 ) ， 


inclusive 将 指向 对 应 的 


ngx_http_core_loc_conf_t 结 构 体 ， 否 则 值 为 


NULL*/ 
ngx_http_core_loc_ conf_t *inclusive,; 
// 指向 


location 的 名 称 


ngx_str_t *name; 


} ngx_http_location_queue_t; 


可 以 看 到 ，ngx_http_location_queue_t 中 的 queue 成 员 将 把 所 有 相关 
的 ngx_http_location_queue_t 结 构 体 串 联 起 来 。 同 时 ， 
ngx_http_location_queue t 将 帮助 用 户 把 所 有 的 location 块 与 其 所 属 的 
server 块 天 联 起 来 。 


那么 ， 哪 些 ngx_http_location_queue_t 结 构 体 会 被 串联 起 来 呢 ? 还 
是 看 10.1 广 的 例子 ，server 块 A 以 及 其 下 所 属 的 location L1 和 location L2 
共 包 括 3 个 ngx_http_core_loc_conf t 结 构 体 ， 它 们 是 相关 的 ， 下 面 看 看 
它们 是 怎样 天 联 起 来 的 ， 如 图 10-6 所 示 。 


每 一 个 ngx_http_core_loc_conf t 都 将 对 应 着 一 个 
ngx_http_location_queue_t 结 构 体 。 在 server 块 A 拥有 的 
ngx_http_core_loc_conf t 结 构 体 中 ，locations 成 员 将 指 同 它 所 属 的 
ngx_http_location_queue_t 结 构 体 ， 这 是 1 个 双 回 链表 的 百 部 。 当 解析 到 
location LI1 块 时 ， 会 创建 一 个 ngx_http_location_queue_t 结 构 体 并 添加 到 
locations 双 回 链 表 的 尾部 ， 该 ngx_http_location_queue_{t 结 构 体 中 的 exact 


或 者 inclusive 指 针 将 会 指向 location L1 所 属 的 ngx_http_core_loc_conf t 结 
构 体 〈 在 location 后 的 表达 式 属于 完全 匹配 时 ，exact 指 针 有 效 ， 人 否则 表 
达 式 将 带 有 通配符 ， 这 时 inclusive 有 效 。exact 优 移 级 高 于 inclusive) ， 
这 样 就 把 location L1 块 对 应 的 ngx_http_core_loc_conf t 结 构 体 ， 以 及 其 
loc_conf 成 员 指 向 的 所 有 HTTP 模 块 在 location LI1 块 内 的 配置 项 与 server 
A 块 结合 了 起 来 。 解 析 到 ]ocation L2 时 会 做 相同 处 理 ， 这 也 残 得 到 了 图 


10-6° 


属于 server A 块 


ngx_http _core _loc _conf _t 


locations 


ngx_http _ core _loc _conf_t 


server A 块 下 create_loc_conf 配 置 项 指针 


ngx_http_location_queue_t 
dueue 
exact 
inclusive 


ene ee 
ngx_http_location_queue_t 


ngx_http _core_loc _conf _t 


属于 location L2 块 


ngx_http _ location_queue_t 


dueue 


exact 
inclusive 


图 10-6 ”同一 个 server 块 下 的 ngx_http_core_loc_conf_t 是 通过 双 癌 链表 关 
联 起 来 的 


事实 上 ，]ocation 之 间 是 可 以 艇 套 的， 那么 它们 之 间 的 关联 关系 又 
是 怎样 的 呢 ? 扩展 一 下 10.1 世 中 的 例 和 于， 即 假设 配置 文件 如 下 : 


http { 
mytest_num 1; 
server { 
server_name A; 
listen 8000; 
listen 80; 
mytest_num 2; 
location /Li1 { 
mytest_num 3; 
location /Li1/CL1 { 
} 
} 


这 时 多 了 一 个 新 的 location 块 L1/CL1， 它 隶属 于 location L1° 此 
时 ， 每 个 location 块 对 应 的 ngx_http_core_loc_conf t 结 构 体 间 是 通过 如 图 
10-7 所 示 的 形式 组 织 起 来 的 。 


ngx_http _core _loc_conf_t 


ngx_http _core_loc_conf + 


rr 属于 server A 块 


server A 块 下 create_loc_conf 配 置 项 指针 


ngx_http_location_ queue_t 


ngx_http _location_ queue_t 


属于 location Ll 块 


inclusive 


ngx_http _location_queue t 
8 p 1 


ngx_http _core _loc_conf_t 


exact 
属于 location L1/CL1 块 


ngx_http _location_queue 1 


exact 
inclusive 


图 10-7 location 块 舱 套 后 ngx_http_core_loc_conf _{t 结 构 体 间 的 关系 


可 以 看 到 ， 仍 然 是 通过 ngx_http_core_loc_conf t 结 构 体 中 的 
locations 指 针 来 容纳 属于 它 的 location 块 的 。 当 locations 为 空 指针 时 ， 表 
示 当 前 的 location 块 下 不 再 能 套 location 块 ， 否 则 表示 还 有 新 的 location 
块 。 在 10.2.4 区 的 合并 配置 项 的 代码 中 可 以 看 到 这 一 点 。 


10.2.4 不 同 级 别 配置 项 的 合并 


考虑 到 HTTP 模 块 可 能 需要 合并 不 同 级 别 的 同名 配置 项 ， 因 此 ， 
HTTP 框 架 为 ngx_http_module _t 接 口 提供 了 merge_srv_conf 方 法 ， 用 于 合 
并 main 级 别 与 srv 级 别 的 server 相 关 的 配置 项 ， 同 时 ， 它 还 提供 了 
merge_loc_conf 方 法 ， 用 于 合并 main 级 别 、srv 级 别 、loc 级 别 的 location 
相关 的 配置 项 。 当 然 ， 如 果 不 存在 合并 不 同 级 别 配置 项 的 场景 ， 那 么 
可 以 不 实现 这 两 个 方法 。 下 面 仍然 以 10.1 节 的 配置 文件 为 例 ， 展 示 了 不 
同 级 别 的 配置 项 结构 体 是 如 何 合并 的 ， 如 图 10-8 所 示 。 


国 本 本 本 本 本 本 国 解析 直属 于 http 块 下 的 main 配置 项 


http 抉 下 create_main_conf 配置 项 指针 | | 模块 5 用 create _main_conf + 创建 的 结构 体 
CT 
http 块 下 create _srv_conf 配置 项 指针 

ELI 模块 5 用 create_loc_conf _t 创 建 的 结构 体 合并 


http 块 下 create _ loc _conf 配置 项 指针 


| 


| 


模块 5 用 create _srv _conf t+ 创建 的 结构 体 


| 


ll lss 解析 http 块 下 server A 的 配置 项 


server A 块 下 create_srv_conf 配置 项 指针 模块 5 用 create_srv_conf 1 创建 的 结构 体 


| 


ah 
对 


server A 块 下 create _loc conf 配置 项 指针 


| 


解析 http 块 下 server A 块 中 
location L 1 的 配置 项 


L 
location L 1 块 下 create_loc _conf 配置 项 指针 


图 10-8 ”main、srv、loc 级 别 的 同名 配置 项 合并 前 的 内 存 示意 图 


图 10-8 以 第 5 个 HTTP 模 块 (通常 是 ngx_http_static_module 模 块 ) 为 
例 ， 展 示 了 在 解析 完 http 块 、server A 块 、location L1 块 后 是 如 何 合并 配 
置 项 的 。 第 5 个 HTTP 模 块 在 解析 这 3 个 配置 块 时 ，create_loc_conf t 方 法 
被 调用 了 3 次 ， 产 生 了 3 个 结构 体 ， 分 别 存放 了 main、srv、loc 级 别 的 
location 相 关 的 配置 项 ， 这 时 可 以 合并 为 location L1 相 关 的 配置 结构 体 ; 


create_SrV_conf { 方 法 被 调用 了 两 次 ， 产 生 了 两 个 结构 体 ， 分 别 存 放 了 


main、srv 级 别 的 配置 项 ， 


体 。 


合并 配置 项 可 能 不 太 容易 理解 ， 


做 个 简 


个 合并 操作 是 在 ngx_http_merge_servers 方 法 下 进 


要 的 介 


这 时 也 可 以 合并 为 server A 块 相关 的 配置 结构 


下 面 我 们 就 在 代码 实现 层面 上 下 


站 绍 ， 同 时 也 对 10.2.2 节 和 10.2.3 节 的 内 容 做 一 个 回顾 。 


它 是 怎么 被 调用 的 : 


/*cmcf 是 


ngx_http_core_module 在 


httpyy 


下 的 全 


局 配 


结构 体 ， 在 


10 .2.2 节 介绍 过 它 


servers 成 员 ， 


ngx_http_core_srv_conf 七 的 指针 ， 


这 是 一 个 动态 数组 ， 它 保 在 


的 


server 块 


*/ 


所 有 


从 而 关联 了 所 


行 的 ， 移 来 简单 地 看 看 


Ep 


g| 


cmcf = ctx->main_conf[ngx_http_core module.ctx_index]; 


// ngx_modules 数 组 中 包含 所 有 的 


Nginx 模 块 


for (m = 0; ngx_modules[m]; m++) { 


// 遍历 所 有 的 


HTTP 模 块 


ngx_module_t 模 块 结构 体 ， 它 的 


IR 


If (ngx_modules[m]->type != NGX_HTTP_MODULE) { 
continue; 


/* ngx_modules[m] 是 一 个 


ctx 成 员 对 于 


HTTP 模 块 来 说 是 


ngx_http_module_t 接 


4 
ngx_http_module t *module = ngx_ modules[m]->ctx; 
// ctx_index 是 这 个 


HTTP 模 块 在 所 有 


HTTP 模 块 中 的 序号 


mi = ngx_modules[m]->ctx_index; 
// 调 


ngx_http_merge_servers 方 法 合并 


ngx_modules[m] 模 块 


rv = ngx_http_merge servers(cf, cmcf, module, mi); 


ngx_http_merge_servers 方 法 不 只 是 合并 了 server 相 天 的 配置 项 ， 它 
同时 也 会 合并 location 相 关 的 配置 项 ， 下 面 再 来 看 看 它 的 实现 ， 代 人 码 如 
到 


static char * ngx_http_merge_servers(ngx_conf t *cf, ngx_http_core main_conf_t 
*cmcf, ngx_http_module t *module, ngx_uint_t ctx_index) 


{ 


char *rv; 

ngx_uint_t s; 

ngx_http_conf_ctx_t *ctx, saved; 
ngx_http_core_loc conf_t *clcf; 
ngx_http_core_srv_conf_t **cscfp; 
/* 从 


ngx_http_core_main_conf_t 的 


servers 动 态 数组 中 可 以 获取 所 有 的 


ngx_http_core_srv_conf t+ 结构 体 


*/ 
cscfp = cmcf->servers.elts,; 
// 注意 ， 这 个 


ctx 是 在 


http{f]} 块 下 的 全 局 


ngx_http_conf_ctx_t 结 构 体 


ctx = (ngx_http_conf_ctx_t *) cf->ctx; 
saved = *ctx; 


// 遍历 所 有 的 
server 块 下 对 应 的 


ngx_http_core_srv_conf_t 结 构 体 


for (s = 0; s < cmcf->servers.nelts; s++) { 
/*srv_conf 将 指向 所 有 的 


HTTP 模 块 产生 的 
server 相 关 的 
srv 级 别 配置 结构 体 


*/ 


ctx->srv_conf = cscfp[s]->ctx->srv_conf; 
// 如 果 当 前 


HTTP 模 块 实现 了 


merge_srv_conf， 则 再 调用 合并 方法 


if (module->merge_Ssrv_conf ) { 
/* 注 意 ， 在 这 里 合并 配置 项 时 ， 


saved.srv_conf[ctx_index] 参 数 是 当前 


HTTP 模 块 在 


http{} 块 下 由 
create_srv_conf 方 法 创建 的 结构 体 ， 而 


cscfp[s]->ctx->srv_conf[ctx_index] 参 数 则 是 在 


server{} 块 下 


create_srv_conf 方 法 创建 的 结构 体 
0/ 

rv = module->merge_srv_conf(cf，Saved,srv_conf[ctx_index]，cscfp[s]-> 
ctx->srv_conf[ctx_index]); 


} 
// 如 果 当 前 


HTTP 模 块 实现 了 


merge_srv_conf， 则 再 调用 合并 方法 


If (module->merge_loc_conf) 
/*cscfp[s]->ctx->loc_conf 这 个 动态 数组 中 的 成 员 都 是 


server{} 块 下 所 有 


HTTP 模 块 的 


create_loc_conf 方 法 创建 的 结构 体 指针 


4 
ctx->loc_conf = cscfp[s]->ctx->loc_conf; 


/* 首 先 将 


httpf{]} 块 下 

main 级 别 与 
server{} 块 下 

srv 级 别 的 
Location 相关 的 结构 体 合 


类 
rv = module->merge_loc_conf(cf，Ssaved,1oc_conf[ctx_index]，cscfp[s]-> 
ctx->loc_conf[ctx_index]); 
/*clcf 是 


server 块 下 


ngx_http_core_module 模 块 使 


create_loc_conf 方 法 产生 的 


ngx_http_core_loc_conf_t 绪 构 体 ， 在 


10.2.3 节 中 曾经 说 过 ， 它 的 


locations 成 员 将 以 双向 链表 的 形式 关联 到 所 有 当前 
server{} 块 下 的 

location 块 

*/ 


clcf = cscfp[s]->ctx->loc_conf[ngx_http_core module.ctx_index]; 


/* 调 


ngx_http_merge_locations 方 法 ,将 


server{} 块 与 其 所 包含 的 


location{} 块 下 的 结构 体 进行 合 


WA 
rv = ngx_http_merge_ locations(cf, clcf->locations, 
cscfp[s]->ctx->loc_conf, 
module, ctx_index); 
} 
} 
了 


ngx_http_merge_locations 方 法 负责 合并 location 相 关 的 配置 项 ， 上 面 
已 经 将 main 级 别 与 srv 级 别 做 过 合并 ， 接 下 来 再 次 将 srv 级 别 与 1joc 级 别 做 


合并 。 每 个 server 块 ngx_http_core_loc_conf t 中 的 locations 双 回 链 表 会 包 
含 所 属 的 全 部 location 块 ， 再 历 它 以 合并 srv、loc 级 别 配置 项 ， 如 下 所 


修 ° 


static char * 
ngx_http_merge_locations(ngx_conf_t *cf, ngx_queue t *locations, 
void **]loc_ conf, ngx_http module t *module, ngx_uint_t ctx_ index) 
{ 

Char *rv; 

ngx_queue _t *d， 

ngx_http_conf_ctx_t *ctx, saved; 

ngx_http_core_loc conf_t *clcf; 

ngx_http_location_queue_t *]1q; 

/* 如 果 


locations 链 表 为 空 ， 也 就 是 说 ， 当 育 


| 


server 块 下 没有 


location 块 ， 则 立刻 返回 


A 
if (locations == NULL) { 
return NGX_CONF_OK; 
} 


ctx = (ngx_http_conf_ ctx_t *) cf->ctx; 
saved = *ctx; 
// 遍历 


locations 双 向 链表 


q = ngx_queue_head(locations); 
q != ngx_queue_sentinel(locations); 
q = ngx_queue_next(q)) 


1q = (ngx_http_location _ queue t *) 9q; 
/* 在 


10.2.3 节 中 曾经 讲 过 ， 如 果 


location 后 的 匹配 字符 串 不 依靠 


Nginx 自 定义 的 通配符 就 可 以 完全 匹配 的 话 ， 则 


exact 指 向 当前 


location 对 应 的 


ngx_http_core_loc_conf_t 结 构 体 ， 否 则 使 


inclusive 指 向 该 结构 体 ， 


exact 的 优先 级 高 于 


inclusive */ 
clcf = lq->exact 1q->exact : 1q->inclusive; 
/*clcf->loc_conf 这 个 指针 数组 里 保存 着 当前 


location 下 所 有 


HTTP 模 块 使 用 


create_loc_conf 方 法 生成 的 结构 体 的 指针 


*/ 
ctx->loc_conf = clcf->loc_conf; 
// 调 


merge_loc_conf 方 法 合并 


Srv.、 


loc 级 别 配 置 项 


rv = module->merge_loc_ conf(cf, lJoc conf[ctx_index], 
clcf->loc conf[ctx_index]); 


/* 注 意 ， 因 为 


location{} 中 可 以 继续 藤 套 


location{} 配 置 块 ， 所 以 是 可 以 继续 合并 的 。 在 


19 ,1 节 的 例子 中 没有 


location 风 套 ， 
10.2.3 节 的 例子 是 体现 出 肉 套 关系 的 ， 可 以 对 照 着 图 
10 -5 来 理解 


#7 
rv = ngx_http_merge_ locations(cf, clcf->locations, clcf->loc_conf, module, 
ctx_index); 


} 
*ctx = saved; 
return NGX_CONF_OK; 


在 针对 每 个 HTTP 模 块 循环 调用 ngx_http_merge_servers 方 法 后 ， 整 
可 以 完成 所 有 的 合并 配置 项 工作 了 。 


10.3 监听 闪 口 的 管理 


监听 端口 属于 server 虚 拟 主机 ， 它 是 由 server{} 块 下 的 listen 配 置 项 
决定 的 。 同 时 ， 它 与 server{} 块 对 应 的 ngx_http_core_srv_conf _t 结 构 体 
密切 相关 ， 本 下 将 介绍 这 两 着 间 的 关系 ， 以 及 监听 端口 的 数据 结构 。 


每 监听 一 个 TCP 端 口 ， 都 将 使 用 一 个 独立 的 ngx_http_conf_ port_t 结 
构 体 来 表示 ， 如 下 所 示 。 


typedef struct { 
// socket 地 址 家 族 


ngx_int_t family; 
// 监听 端 


in_port_t port 


// 监听 的 端口 下 对 应 着 的 所 有 


ngx_http_conf_addr_t 地 址 


ngx_array_t addrs; 
} ngx_http_conf_port_t; 


这 个 保存 着 监听 端口 的 ngx_http_conf_port_t 将 由 全 局 的 
ngx_http_core_main_conf {t 结 构 体 傈 存 。 下 面 再 来 看 一 下 ports 容 硕 ， 如 
下 所 示 ” 


typedef struct { 
// 存放 着 该 


http 人 配置 块 下 监听 的 所 有 


ngx_http_conf_port_t 端 


ngx_array_t *ports; 


} ngx_http_core_ main_conf_t; 


在 前 面 的 代码 中 ，ngx_http_conf_port_t 和 的 addrs 动 态 数组 可 能 不 太 
容易 理解 。 可 先 回 顾 一 下 listen 配 置 项 的 语法 ， 在 10.1 市 的 例子 中 ， 对 
同一 个 端口 8000， 我 们 可 以 同时 监听 127.0.0.1:8000、 
173.39.160.51:8000 这 两 个 地 址 ， 当 一 台 物 理 机 器 具备 多 个 IP 地 址 时 这 
是 很 有 用 的 。 具 体 到 HTTP 框 架 的 实现 上 ，Nginx 是 使 用 
ngx_http_conf addr t 结 构 体 来 表示 一 个 对 应 着 具体 地 址 的 监听 端口 
的 ， 因 此 ， 一 个 ngx_http_conf_port_t 将 会 对 应 多 个 
ngX_http_conf addr tf， 而 ngx_http_conf_addr t 就 是 以 动态 数组 的 形式 保 
存在 addrs 成 员 中 的 。 


下面 再 来 看 看 ngx_http_conf_addr t 的 定义 ， 如 下 所 示 。 


typedef struct { 
// 监听 套 接 字 的 各 种 属性 


ngx_http_listen opt_t opt; 
/A* 以 下 


3 个 散 列 表 用 于 加 速 寻 找到 对 应 监听 端口 上 的 新 连接 ， 确 定 到 底 使 用 哪个 


serverf{]} 虚 拟 主机 下 的 配置 来 处 理 它 。 所 以 ， 散 列表 的 值 就 是 


ngx_http_core_srv_conf_t 结 构 体 的 地 址 


*/ 
// 完全 匹配 


server name 的 散 列 表 


ngx_hash_t hash 


// 通配符 前 置 的 散 列表 


ngx_hash wildcard t *wc_head; 
// 通配符 后 置 的 散 列 表 


ngx_hash_wildcard t *wc_ tail; 
#if (NGX_PCRE) 
// 下 面 的 


regex 数 组 中 元 素 的 个 数 


ngx_uint_t nregex,; 
/*regex 指 向 静态 数组 ， 其 数组 成 员 就 是 


ngx_http_server_name_t 结 构 体 ， 表 示 正 则 表达 式 及 其 匹配 的 


server 人 虚拟 主机 


%/ 

ngx_http_server_name_t *regex; 
#endif 

// 该 监听 端口 下 对 应 的 默认 


server 人 虚拟 主机 


ngx_http_core_srv_conf_t *default_ server; 
// servers 动 态 数组 中 的 成 员 将 指向 


ngx_http_core_srv_conf tt 结构 体 


ngx_array_t servers; 
} ngx_http_conf_addr_t; 


在 上 面 的 servers 动 态 数组 中 ， 保 存 的 数据 类 型 是 
ngx_http_core_srv_conf tx**， 人 简单 来 说 ， 束 是 由 servers 数 组 把 监听 的 端 
口 与 serverf} 虚 拟 主机 关联 起 来 了 。 图 10-9 展 示 了 10.1 和 的 例子 中 监听 
问 口 与 server{f} 虚 拟 主机 间 在 内 存 中 的 关系 。 


ngx_http _conf_port _t 


+family 


ngx_http_core_main_conf_t 


监听 端口 8000 


server A 配置 块 下 的 


ngx_http _core _loc _conf tt 


server B 配置 块 下 的 
ngx_http _core _loc _conf _t 


图 10-9 监听 端口 与 server{} 庶 拟 主机 间 的 关系 


下 面 来 解释 一 下 图 10-9。 整 个 http{} 块 下 共 监 听 了 3 个 端口 ， 分 别 是 
80、8000、8080， 因 此 ，ngx_http_core_main_conf t 中 的 ports 动 态 数组 
有 3 个 ngx_http_conf_port_{t 成 员 存放 这 3 个 端口 。 除 了 8000 端 口 对 应 了 两 
个 ngx_http_conf_addr t 结 构 体外 (分 别 是 127.0.0.1:8000 和 
173.39.160.51:8000) ，80 和 8080 都 相当 于 默认 监听 了 该 端口 下 的 所 有 
地 址 (实际 上 ，listen 80 就 相当 于 listen*.80) ， 因 此 ， 这 两 个 端口 各 上 自 
对 应 了 一 个 ngx_http_conf_addr t 结 构 体 。 每 个 监听 地 址 
ngx_http_conf addr t 时 servers 动 态 数 组 中 关联 着 监 听 地 址 对 应 的 
server{} 虚 拟 主机 ， 根 据 10.1 市 的 例子 可 以 知道 ，server A 配 置 块 对 应 着 
监听 地 址 *.80 和 127.0.0.1:8000， 而 server B 配 置 块 对 应 着 监听 地 址 
*.80、*.8080 和 173.39.160.51:8000 。 


对 于 每 一 个 监听 地 址 ngx_http_conf addr tf， 都 会 有 8.3.1 节 中 介绍 
过 的 ngx_listening_t 与 其 相对 应 ， 而 ngx_listening_t 的 handler 回 调 方法 设 
置 为 ngx_http_init connection， 所 以 ， 狐 的 TCP 连 接 成 功 建立 后 都 会 调 
用 ngx_http_init connection 方 法 初始 化 HITP 相 关 的 信息 ， 第 11 章 将 会 详 


细 介 绍 ngx_http_init_connection 方 法 的 实现 。 


10.4 ”server 的 快速 检索 


在 10.2.2 节 中 可 以 看 到 ， 每 一 个 虚拟 主机 serverf} 配 置 块 都 由 一 个 
ngx_http_core_srv_conf_t 结 构 体 来 标识 ， 这 些 ngx_http_core_srv_conf { 
又 是 通过 全 人 http_core_main_conf t 结 构 中 的 servers 动 态 数 组 天 
联 起 来 的 。 这 意味 着 当 开始 处 理 一 个 HTTP 痢 连接 时 ， 接 收 到 HTTP 头 
部 并 取 到 Host 后 ， 需 要 遍历 ngx_http_core_main_conf_t 的 servers 数 组 才 
能 找到 与 server name 配 置 项 匹配 的 虚拟 主机 配置 块 ， 这 样 的 时 间 复 杂 
度 显 然 是 不 可 接受 的 ， 因 为 当 nginx.conf 配 置 文件 中 拥有 数 以 百 计 的 
server{} 块 时 ， 查 询 效 率 吏 太 低 了 。 于 是 ，HTTP 框 架 使 用 了 第 7 革 中 介 
绍 过 的 散 列 表 来 存放 虚拟 主机 ， 其 中 每 个 元 素 的 关键 字 是 server name 
字符 串 ， 而 值 则 是 ngx_http_core_srv_conf t 结 构 体 的 指针 。 


在 10.3 世 中 介绍 过 ， 负 责 监 听 一 个 问 口 地 址 的 
ngx_http_conf_addr_t 结 构 体 拥有 下 面 3 个 成 员 : hash、wc_head、 
wc_tai， 这 3 个 成 员 对 应 着 7.7.3 节 中 介绍 过 的 市 通配符 的 散 列 表 。 这 个 
带 通 配 符 的 散 列 表 的 使 用 方法 (包括 如 何 构 造 、 检 索 ) 在 7.7 节 中 已 详 
细 描 述 过 ， 这 里 不 再 长 述 。 


10.5 location 的 快速 检索 


从 10.2.3 市 中 可 以 了 解 到 ， 每 一 个 server 块 可 以 对 应 着 多 个 location 
块 ， 而 一 个 location 块 还 可 以 继续 舱 套 多 个 location 块 。 每 一 批 location 
块 是 通过 双 回 链表 与 它 的 父 配置 块 (要 么 属于 server 块 ， 要么 属于 
location 块 ) 关联 起 来 的 。 由 双向 链表 的 查询 效率 可 以 知道 ， 当 一 个 请 
求 根据 10.4 地 中 描述 过 的 散 列 表 快 速 查 询 到 server 块 时 ， 必 须 遇 历 其 下 
的 所 有 location 组 成 的 双 同 链表 才能 找到 与 其 URI 匹 配 的 location 配 置 
块 ， 这 也 是 用 户 无 法 接受 的 。 下 面 看 看 HTTP 框 以 又 是 怎样 通过 静态 的 
二 又 碍 找 树 来 保存 location 的 。 


// cmcf 就 是 该 


http 块 下 全 局 的 


ngx_http_core_main_conf_t 结 构 体 


cmcf = ctx->main_conf[ngx_http_core module.ctx_index]; 


/*cscfp 指 向 保存 所 有 


ngx_http_core_srv_conf_t 结 构 体 指针 的 
servers 动 态 数组 的 第 

于 作 元 过 

*/ 

cscfp = cmcf->servers.elts; 


// 遍历 
http 块 下 的 所 有 


server 块 


for (s = 0; s < cmcf->servers.nelts; s++) { 
/*clcf 是 


server 块 下 的 


ngx_http_core_loc_conf_t 结 构 体 ， 


10 .2.3 节 曾 经 介绍 过 它 的 
locations 成 员 以 双向 链表 关联 着 隶属 于 这 个 


server 块 的 所 有 


location 块 对 应 的 


ngx_http_core_loc_conf_t 结 构 体 


< 
clcf = cscfp[s]->ctx->loc_conf[ngx_http_core module.ctx_index]; 
/* 将 


ngx_http_core_loc_conf_t 组 成 的 双向 链表 按照 


location 匹 配 字 符 串 进行 排序 。 注 意 : 这 个 操作 是 递归 进行 的 ， 如 果 某 个 


location 块 下 还 具有 其 他 


location， 那 么 它 的 


locations 链 表 也 会 被 排序 


*/ 

If (ngx_http_init_locations(cf, cscfp[s], cilcf) != NGX_OK) { 
return NGX_CONF_ERROR ， 

} 

/* 根 据 已 经 按照 


JIocation 字 符 串 排序 过 的 双向 链表 ， 快 速 地 构建 静态 的 二 又 查找 树 。 与 


ngx_http_init_locations 方 法 类 似 ， 这 个 操作 也 是 递归 进行 的 


*/ 
If (ngx_http_init_static location_ trees(cf, clcf) != NGX_OK) { 
return NGX_CONF_ERROR ， 


} 
} 


注意 ， 这 里 的 二 义 查 找 树 并 不 是 第 7 章 中 介绍 过 的 红 黑 树 ， 不 过 ， 
为 什么 不 使 用 红 黑 树 呢 ? 因为 location 是 ea > 
静态 不 变 的 ， 不 存在 运行 过 程 中 在 树 中 添加 或 者 删除 location 的 场景 ， 
而 且 红 黑 树 的 查询 效率 也 没有 重新 构造 的 静态 的 完全 平衡 二 叉 树 高 。 


这 棵 静态 的 二 又 平衡 查找 树 是 用 ngx_http_location_tree_node_t 结 构 
体 来 表示 的 ， 如 下 所 示 。 


typedef struct ngx_http_location tree node s ngx_http_location tree node t; 
struct ngx_http_location tree node sf{ 
// 左 子 树 


ngx_http_location tree node 上 *left; 
// 右 子 树 


ngx_http_location tree node 上 *right,; 
// 无 法 完全 匹配 的 


location 组 成 的 树 


ngx_http_location tree node 上 *tree; 
/* 如 果 


location 对 应 的 


URI 匹 配 字符 串 属 于 能 够 完全 匹配 的 类 型 ， 则 


exact 指 向 其 对 应 的 


ngx_http_core_1oc_conf _t 结 构 体 ， 否 则 为 


NULL 空 指针 


*/ 
ngx_http_core_loc conf_t *exact 


/* 如 果 


location 对 应 的 


URI 匹 配 字符 串 属于 无 法 完全 匹配 的 类 型 ， 则 


inclusive 指 向 其 对 应 的 


ngx_http_core_loc_conf_t 结 构 体 ， 否 则 为 
NULL 空 指针 
*y 


ngx_http_core_loc conf_t *inclusive; 
// 自动 重 定向 标志 


u_char auto_redirect,; 
// name 字 符 串 的 实际 长 度 


u_char len; 
// name 指 向 


location 对 应 的 


URI 匹 配 表达 式 


,har nane[]; 

HTTP 框 架 在 ngx_http_core_module 模 块 中 定义 了 
ngx_http_core_find_location 方 法 ， 用 于 从 静态 二 又 查找 树 中 快速 检索 
到 ngx_http_core_ loc_conf t 结 构 体 ， 这 在 第 11 章 探讨 HTTP 请 求 的 处 理 
过 程 时 将 会 页 到 。 


10.6 ” HTTP 请 求 的 11 个 处 理 阶段 


Nginx 为 什么 要 把 HTTP 请 求 的 处 理 过 程 分 为 多 个 阶段 呢 ? 这 要 从 
第 8 章 介 绍 过 的 “一 切 轩 模块 ?说 起 。 Nginx 的 模块 化 设计 使 得 每 一 个 
HTTP 模 块 可 以 仅 专 注 于 完成 一 个 独立 的 、 人 简单 的 功能 ， 而 一 个 请 求 的 
完整 处 理 过 程 可 以 由 无 数 个 HTTP 模 块 共同 合作 完成 。 这 种 设计 有 非常 
好 的 简单 性 、 可 测试 性 、 可 扩展 性 ， 然 而 ， 当 多 个 HTTP 模块 流水 式 地 
处 理 同一 个 请 求 时 ， 单 一 的 处 理 顺序 是 无 法 满足 灵活 性 需求 的 ， 每 一 
个 正在 处 理 请 求 的 HTTP 模 块 很 难 灵活 、 有 效 地 指定 下 一 个 HTTP 处 理 
模块 是 哪 一 个 。 而 且 ， 不 划分 处 理 阶 段 也 会 让 HTTP 请 求 的 完整 处 理 流 
程 难 以 管理 ， 每 一 个 HTTP 模 块 也 很 难 正确 地 将 自己 插入 到 完整 流程 中 
的 合适 位 置 中 。 


因此 ，HTTP 框 染 依 据 常 见 的 处 理 流程 将 处 理 阶段 划分 为 11 个 阶 
段 ， 其 中 每 个 处 理 阶段 都 可 以 由 任意 多 个 HTTP 模 块 流水 式 地 处 理 请 
求 。 先 来 回顾 一 下 第 3 革 中 曾经 提 到 过 的 ngx_http_phases 阶 段 的 定义 ， 
I 


typedef enum { 
// 在 接收 到 完整 的 


HTTP 头 部 后 处 理 的 


HTTP 阶 段 


NGX_HTTP_POST_READ_PHASE = 9， 
/* 在 将 请 求 的 


URI 与 


location 表 达 式 匹配 前 ， 修 改 请 求 的 


URI (所 谓 的 重 定向 ) 是 一 个 独立 的 


HTTP 阶 段 

*/ 
NGX_HTTP_SERVER_REWRITE_PHASE, 
/* 根 据 请 求 的 


URI 和 寻找 匹配 的 


location 表 达 式 ， 这 个 阶段 只 能 由 


ngx_http_core_module 模 块 实现 ， 不 建议 其 他 


HTTP 模 块 重新 定义 这 一 阶段 的 行为 


*/ 
NGX_HTTP_FIND_CONFIG_PHASE, 
/* 在 


NGX_HTTP_FIND_CONFIG_PHASE 阶 段 寻 找到 匹配 的 


location 之 后 再 修改 请 求 的 


URI*/ 
NGX_HTTP_REWRITE_PHASE, 
/这 一 阶段 是 用 于 在 


rewrite 重 写 
URL 后 ， 防 止 错误 的 
nginx.conf 配 置 导致 死 循 环 (递归 地 修改 


URI) ， 因 此 ， 这 一 阶段 仅 由 


ngx_http_core_module 模 块 处 理 。 ， 探 制 死 循环 的 方式 很 简 和 


廿 
一 


l 


rewrite 的 次 数 ， 如 果 一 个 请 求 超过 


10 次 重 定向 


; 就 认为 进入 了 


rewrite 死 循环 ， 这 时 在 


NGX_HTTP_POST_REWRITE_PHASE 阶 段 就 会 向 用 户 ; 


5909， 表 示 服 务 器 内 部 错误 


网 


*/ 
NGX_HTTP_POST_REWRITE_PHASE， 
/表示 在 处 理 


NGX_HTTP_ACCESS_PHASE 阶 段 决定 请 求 的 访问 权限 前 ， 


HTTP 模 块 可 以 介入 的 处 理 阶段 


先 检查 


NGX_ _HTTP_PREACCESS_ PHASE, 
// 这 个 阶段 用 于 让 
HTTP 模 块 判 断 是 否 允 许 这 个 请 求 访问 


Nginx 服 务 器 


NGX_HTTP_ACCESS_PHASE, 
/在 


NGX_HTTP_ACCESS_PHASE 阶 段 
HTTP 模 块 的 
handler 处 理 函 数 返 回 不 允许 访问 的 错误 码 时 ( 


也 
蚊 


NGX_HTTP_FORBIDDEN 或 者 


NGX_HTTP_UNAUTHORIZED) ， 这 里 将 负责 向 


NGX_HTTP_ACCESS_PHASE 阶 段 收 尾 
本 
NGX_HTTP_POST_ACCESS_PHASE, 
/* 这 个 阶段 完全 是 为 
项 而 设立 的 ， 当 
HTTP 请 求 访问 静态 文件 资源 时 ， 


try_files 配 置 


try_files 配 置 项 可 以 使 这 


try_files 中 指定 的 下 一 个 静态 资源 。 这 


NGX_HTTP_TRY_FILES_PHASE 阶 段 


中 实现 的 


*/ 
NGX_HTTP_TRY_FILES_PHASE, 
// 用 于 处 理 


HTTP 请 求 内 容 的 阶段 ， 


这 是 大 部 分 


HTTP 模 块 最 愿意 介入 的 阶段 


NGX_HTTP_CONTENT_PHASE, 
A/* 处 理 完 请 求 后 记录 日 志 的 阶段 。 例 如 ， 


ngx_http_log_module 模 块 就 在 这 


handler 处 理 方 法 ， 


HTTP 请 求 处 理 完 


access_1og 访 问 日 志 


*/ 
NGX_HTTP_LOG_PHASE 
} ngx_http_phases ; 


个 请 求 顺序 地 访问 多 


发 送 拒绝 


个 静态 文件 


个 功能 完全 是 在 


个 阶段 中 加 入 了 一 


六 


服务 的 错误 响应 。 


资源 ， 如 果 某 一 次 访问 失败 ， 则 继 纪 


此 ， 这 个 阶段 实际 上 


于 给 


卖 访 问 


对 于 这 11 个 处 理 阶 段 ， 有 些 阶段 是 必 备 的 ， 有 些 阶段 是 可 选 的 ， 
当然 也 可 以 有 多 个 HTTP 模 块 同时 介入 同一 阶段 (这 时 ， 将 会 在 一 个 阶 
段 中 按照 这 些 HTTP 模 块 的 ctx_index 顺 序 来 依次 执行 它们 提供 的 handler 
处 理 方法 ) 。 在 10.6.1 广 中 将 会 介绍 这 11 个 阶段 共同 适用 的 规则 ， 在 
10.6.2 让 ~10.6.12 市 则 会 摘 述 这 些 具 体 的 处 理 阶 段 。 


@@ 注意 ngx_htp_phases 定 义 的 11 个 阶段 是 有 顺序 的 ， 必 须 按照 
其 定义 的 顺序 执行 。 同 时 也 要 意识 到 ， 并 不 是 说 一 个 用 户 请 求 最 多 只 
能 经 过 11 个 HTTP 模 块 提供 的 ngx_http_handler_pt 方 法 来 处 理 ， 


NGX_HTTP_POST_ READ PHASE、 
NGX_HTTP_SERVER_REWRITE_PHASE、 
NGX_HTTP_REWRITE_PHASE、NGX_HTTP_PREACCESS_PHASE、 
NGX_HTTP_ACCESS_PHASE、NGX_HTTP_CONTENT_PHASE、 
NGX_HTTP LOG_PHASE 这 7 个 阶段 可 以 包括 任意 多 个 处 理 方 法 ， 

们 是 可 以 同时 作用 于 同一 个 用 户 请 求 的 。 而 
NGX_HTTP_FIND_CONFIG PHASE 、 
NGX_HTTP_POST_REWRITE_PHASE 、 
NGX_HTTP_POST_ACCESS_PHASE 、 

NGX_HTTP TRY FILES_PHASE 这 4 个 阶段 则 不 允许 HTTP 模 块 加 入 自 
己 的 ngx_http_handler_pt 方 法 处 理 用 户 请 求 ， 它 们 仪 由 HTTP 框 架 实现 。 


10.6.1 HTTP 处 理 阶 段 的 普 适 规则 


下 面 先 来 看 看 HTTP 了 阶段 的 定义 ， 它 包括 checker 检 查 方法 和 handler 
处 理 方法 ， 如 下 所 示 。 


typedef struct ngx_http_phase_handler s ngx_http_phase_handler 七 ， 


/* 一 个 


HTTP 处 理 阶 段 中 的 


checker 检 查 方法 ， 仅 可 以 


HTTP 框 架 实现 ， 以 此 控制 
HTTP 请 求 的 处 理 流程 


*/ 
typedef ngx_int_t (*ngx_http_phase handler_pt) (ngx_http_request _t *r, 
ngx_http_phase_handler_t *ph); 

pa 


es 


HTTP 模 块 实现 的 


handler 处 理 方法 ， 这 个 方法 在 第 


3 章 中 曾经 


ngx_http_mytest_handler 方 法 实现 过 


4 
typedef ngx_int_t (*ngx_http_handler_pt)(ngx_http_request t *r); 
// 注意 : 


ngx_http_phase_handler_t 结 构 体 仅 表示 处 理 阶 段 中 的 一 个 处 理 方法 


struct ngx_http_phase_handler_ s { 
/* 在 处 理 到 某 一 个 


HTTP 阶 段 时 ， 


HTTP 框 架 将 会 在 


checker 方 法 已 实现 的 前 提 先 调 


checker 方 法 来 处 理 请 求 ， 而 不 会 直接 调用 任何 阶段 中 的 


handler 方 法 ， 只 有 在 
checker 方 法 中 才 会 去 调用 
handler 方 法 。 因 此 ， 事 实 上 所 有 的 


checker 方 法 都 是 由 框架 中 的 


ngx_http_core_module 模 块 实现 的 ， 且 普通 的 


HTTP 模 块 无 法 重 定义 


checker 方 法 


*/ 
ngx_http_phase_handler_pt checker; 
/* 除 


ngx_http_core_module 模 块 以 外 的 


HTTP 模 块 ， 只 能 通过 定义 
handler 方 法 才能 介入 某 一 个 


HTTP 处 理 阶 段 以 处 理 请 求 


3 
ngx_http_handler_pt handler; 
// 将 要 执行 的 下 一 个 


HTTP 处 理 阶段 的 序号 


/* next 的 设计 使 得 处 理 阶段 不 必 按 顺序 依次 执行 ， 既 可 以 向 后 跳跃 数 个 阶段 继续 执行 ， 也 可 以 跳跃 到 之 
前 曾经 执行 过 的 某 个 阶段 重新 执行 。 通 常 ， 


next 表 示 下 一 个 处 理 阶段 中 的 第 


性 人 


ngx_http_phase_handler_t 处 理 方法 
*/ 
ngx_uint_t next; 
@ 注意 。 通常， 在 任意 一 个 ngx_http_phases 阶 段 ， 都 可 以 拥有 专 
个 或 多 个 ngx_http_phase_handler_t 结 构 体 ， 其 含义 更 接近 于 某 个 HTTP 


模块 的 处 理 方法 。 


一 个 http{} 块 解析 完毕 后 将 会 根据 nginx.conf 中 的 配置 产生 由 
ngx_http_phase_handler_t 组 成 的 数组 ， 在 处 理 HTTP 请 求 时 ， 一 般 情 况 
下 这 些 阶段 是 顺序 向 后 执行 的 ， 但 ngx_http_phase_handler_t 中 的 next 成 


员 使 得 它们 也 可 以 非 顺 序 执 行 。ngx_http_phase_engine_t 结 构 体 就 是 所 
有 ngx_http_phase_handler_t 组 成 的 数组 ， 如 下 所 示 。 


typedef struct { 
/*handlers 是 


ngx_http_phase_handler_t 构 成 的 数组 首 地 址 ， 它 表示 一 个 请 求 可 能 经 历 的 所 


ngx_http_handler_pt 处 理 方法 


*/ 
ngx_http_phase handler_t *handlers; 
/* 表 示 


NGX_HTTP_SERVER_REWRITE_PHASE 阶 段 第 


全 人 


ngx_http_phase_handler_t 处 理 方法 在 


handlers 数 组 中 的 序号 ， 用 于 在 执行 


HTTP 请 求 的 任何 阶段 中 快速 跳 转 到 


NGX_HTTP_SERVER_REWRITE_PHASE 阶 段 处 理 请 求 


wd 


*/ 
ngx_uint_t server_rewrite_index; 
/* 表 示 


NGX_HTTP_REWRITE_PHASE 阶 段 第 


1 个 


ngx_http_phase_handler_t 处 理 方法 在 


handlers 数 组 中 的 序号 ， 用 于 在 执行 


HTTP 请 求 的 任何 阶段 中 快速 跳 转 到 


NGX_HTTP_REWRITE_PHASE 阶 段 处 理 请 求 


A 
ngx_uint_t location _ rewrite_index; 
} ngx_http_phase_engine_t; 


可 以 看 到 ，ngx_http_phase_engine_t 中 保存 了 在 当前 nginx.conf 配 置 
下 ,一 个 用 户 请 求 可 能 经 历 的 所 有 ngx_http_handler_pt 处 理 方法 ， 这 是 
所 有 HTTP 模 块 可 以 合作 处 理 用 户 请 求 的 天 键 ! 这 个 


ngx_http_phase_engine_t 结 构 体 是 保存 在 全 局 的 
ngx_http_core_main_conf t 结 构 体 中 的 ， 如 下 所 示 。 


typedef struct { 
/* 由 下 面 各 阶段 处 理 方 法 构成 的 


phases 数 组 构建 的 阶段 引擎 才 是 流水 式 处 理 


HTTP 请 求 的 实际 数据 结构 


*/ 


ngx_http_phase_engine_t phase_engine; 
/* 用 于 在 


HTTP 框 架 初 始 化 时 帮助 各 个 


HTTP 模 块 在 任意 阶段 中 添加 


HTTP 处 理 方法 ， 它 是 一 个 有 


11 个 成 员 的 


ngx_http_phase_t 数 组 ， 其 中 每 一 个 


ngx_http_phase_t 结 构 体 对 应 一 个 


HTTP 阶 段 。 在 


HTTP 框 架 初 始 化 完毕 后 ， 运 行 过 程 中 的 


phases 数 组 是 无 用 的 


村 
ngx_http_phase_t phases[NGX_HTTP_LOG_PHASE + 1]; 


} ngx_http_core main_conf_t; 


在 ngx_http_core_main_conf_t 中 关于 HTTP 阶 段 有 两 个 成 员 : 
phase_engine 和 phases， 其 中 phase_engine 控 制 运行 过 程 中 一 个 HTTP 请 
求 所 要 经 过 的 HTTP 处 理 阶 段 ， 它 将 配合 ngx_http_request_t 结 构 体 中 的 
phase_handler 成 员 使 用 (phase_handler 指 定 了 当前 请 求 应 当 执 行 哪 一 个 
HTTP 阶 段 ) ; 而 phases 数 组 更 像 一 个 临时 变量 ， 它 实际 上 仅 会 在 Nginx 


启动 过 程 中 用 到 ， 它 的 唯一 使 命 是 按照 11 个 阶段 的 概念 初始 化 
phase_engine 中 的 handlers 数 组 。 下 面 看 一 下 ngx_http_phase t 的 定义 。 


typedef struct 
// handlers 动 态 数 组 保存 着 每 一 个 


HTTP 模 块 初始 化 时 添加 到 当前 阶段 的 处 理 方法 


ngx_array_t handlers,; 
} ngx_http_phase_t; 


在 HTTP 框 染 的 初始 化 过 程 中 ， 任 何 HTTP 模 块 都 可 以 在 
ngx_http_module_t 接 口 的 RAR 中 将 目 定义 的 方法 添加 
到 handler 动 态 数组 中 ， 这 样 ， 这 个 方法 吏 会 最 终 添 加 到 phase_engine 中 

(注意 ， 第 3 章 中 mytest 模 块 并 没有 把 ngx_http_mytest_handler 方 法 加 入 
到 phases 的 handlers 数 组 中 ， 这 是 因为 对 于 
NGX_HTTP_CONTENT_PHASE 阶 段 来 说 ， 还 有 另 一 种 初始 化 方法 ， 
在 10.6.11 节 中 我 们 会 介绍 ) 。 在 第 11 章 中 可 以 看 到 这 些 HTTP 阶 段 是 如 
何 执 行 的 。 


下 面 将 会 简要 介绍 这 11 个 HTTP 处 理 阶段 ， 读 者 关注 重点 是 每 个 阶 
段 的 checker 方 法 都 做 了 些 什 么 。 


10.6.2 NGX_HTTP_ POST_READ_PHASE 阶 段 


当 HTTP 框 架 在 建立 的 TCP 连 接 上 接收 到 客户 发 送 的 完整 HTTP 请 求 
头 部 时 ， 开 始 执行 NGX_HTTP POST_READ_PHASE 阶 段 的 checker 方 


法 。 下 面 完 来 看 看 它 的 checker 方 法 ngx_http_core_generic_phase， 这 是 
一 个 很 典型 的 checker 方 法 ， 下 面 瓯 给 出 相关 代码 ， 以 便 读 者 对 checker 


ngx_int_t ngx_http_core_generic_phase(ngx_http_request_t *r, 
ngx_http_phase_handler_t *ph) 


// 调用 这 一 阶段 中 各 


HTTP 模 块 添加 的 


handler 处 理 方 法 


ngx_int_t rc = ph->handler(r); 
/* 如 果 


handler 方 法 返 


NGX_O0K， 之 后 将 进入 下 一 个 阶段 处 理 ， 而 不 会 理会 当前 阶段 中 是 否 还 有 其 他 的 处 理 方法 


bh 
If (rc == NGX_OK) { 
r->phase_handler = ph->next; 
return NGX_AGAIN,; 


} 
/* 如 果 


handler 方 法 返 


NGX_DECLINED， 那 么 将 进入 下 一 个 处 理 方法 ， 这 个 处 理 方法 既 可 能 属于 当前 阶段 ， 也 可 能 属于 下 一 个 阶段 。 注 


意 返 下 


NGX_OK 与 


NGX_DECLINED 之 间 的 区 别 


WA 
if (rc == NGX_DECLINED) { 
r->phase_handler++; 
return NGX_AGAIN,; 


} 
/* 如 果 


handler 方 法 返 


NGX_AGAIN 或 者 


NGX_DONE， 那 么 当前 请 求 将 仍然 停留 在 这 一 个 处 理 阶 段 中 


*/ 
if (rc == NGX_AGAIN || rc == NGX_DONE) { 
return NGX_OK; 


} 
/* 如 果 


handler 方 法 返回 


NGX_ERROR 或 者 类 似 


NGX_HTTP_ 开 头 的 返回 码 ， 则 调 


ngx_http_finalize_ request 结 束 请 求 


*/ 


ngx_http_finalize_request(r, rc); 
return NGX_OK， 


任意 HTTP 模 块 需要 在 NGX HTTP POST READ PHASE 阶 段 处 理 


HTTP 请 求 时 ， 


必须 首先 在 ngx_http_core_main_conf t 结 构 体 中 的 


phases[INGX_HTTP_POST_READ_PHASE] 动 态 数组 中 添加 自己 实现 的 
ngx_http_handler_ pt 方法。 在 此 阶段 中 ，ngx_http_handler_ pt 方法 的 返回 
值 可 以 产生 4 种 不 同 的 影响 ， 总 结 见 表 10-1。 


表 10-1 NGX_HTTP POST READ _ PHASE、 


NGX_HTTP PREACCESS PHASE、NGX_HTTP LOG_PHASE 阶 段 下 
HTTP 模 块 的 ngx_http_handler_pt 方 法 返回 值 意义 


返回 值 


NGX OK 


返回 值 
NGX_DECLINED 
NGX_AGAIN 
NGX_DONE 


NGX ERROR 
其 他 


涡 
< 


执行 下 一 个 ngx_http_phases 阶段 中 的 第 一 个 ngx_http handler pt 处 理 方法 。 这 意味 着 两 
点 : QD 即使 当前 阶段 中 后 续 还 有 一 些 HTTP 模块 设置 了 ngx_http handler pt 处 理 方法 ， 返回 
NGX_OK 之 后 它们 也 是 得 不 到 执行 机 会 的 ; 名 如 果 下 一 个 ngx_http_phases 阶段 中 没有 任何 
HTTP 模块 设置 了 ngx_http_handler_pt 处 理 方法 ， 将 再 次 寻找 之 后 的 阶段 ， 如 此 循环 下 去 

( 续 ) 
按照 顺序 执行 下 一 个 ngx_http_handler pt 处 理 方法 。 这 个 顺序 就 是 ngx_http_phase_ 
engine t 中 所 有 ngx_http_ phase handler t 结构 体 组 成 的 数组 的 顺序 

当前 的 ngx_http_handler_pt 处理 方法 尚未 结束 ， 这 意味 着 该 处 理 方法 在 当前 阶段 有 机 会 再 
次 被 调用 。 这 时 一 般 会 把 控制 权 交 还 给 事件 模块 ， 当 下 次 可 写 事件 发 生 时 会 再 次 执行 到 该 
ngx_http_ handler pt 处 理 方法 


需要 调用 ngx_http_finalize_ request 结束 请 求 


目前 ， 官 方 的 ngx_http_realip_module 模 块 是 从 
NGX_HTTP_POST_READ_PHASE 阶 段 介入 以 处 理 HTTP 请 求 的 ， 它 在 
postconfiguration 方 法 中 是 这 样 将 目 定义 的 ngx_http_handler_pt 处 理 方 法 
添加 a 到 HTTP 框 染 中 的 ， 如 下 所 示 。 


// 这 个 


ngx_http_realip_init 方 法 实际 上 就 是 


postconfiguration 接 口 的 实现 


static ngx_int_t ngx_http_realip_ init(ngx_conf_t *cf) 


{ 


ngx_http_handler_pt *h; 
// 首先 获取 到 全 局 的 


ngx_http_core_main_conf_t 结 构 体 


ngx_http_core_main_conf t *cmcf = ngx_http_conf_get_module_main_conf( cf, 
ngx_http_core_module)， 
/*phases 数 组 中 有 


11 个 成 员 ， 取 出 


NGX_HTTP_POST_READ_PHASE 阶 段 的 


handlers 动 态 数组 ， 向 其 中 添加 


ngx_http_handler_pt 处 理 方法 ,这样 


ngx_http_realip_module 模 块 就 介入 
HTTP 请 求 的 


NGX_HTTP_POST_READ_PHASE 处 理 阶 段 了 


WA 


h = ngx_array_push(&cmcf->phases[NGX_HTTP_POST_READ_PHASE] .handlers); 
if (h == NULL) { 
return NGX_ERROR; 


} 
/* ngx_http_realip_handler 方 法 就 是 实现 了 


ngx_http_handler_pt 接 口 的 方法 


4 
*h = ngx_http_realip_handler,; 
/* 实 际 上 ; 同一 个 


HTTP 模 块 的 同一 个 


ngx_http_realip_handler 方 法 ， 完 全 可 以 设置 到 两 个 不 同 的 阶段 中 的 。 例 如 ， 


phases[NGX_HTTP_PREACCESS_PHASE .handlers] 动 态 数 组 中 也 添加 了 
ngx_http_realip_handler 方 法 


yf 
h = ngx_array_push(&cmcf->phases[NGX_HTTP_PREACCESS_PHASE] .handlers); 
if (h == NULL) { 
return NGX_ERROR; 


} 
/*ngx_http_realip_handler 处 理 方法 同时 介入 了 


NGX_HTTP_POST_READ_PHASE 、 


NGX_HTTP_PREACCESS_PHASE 这 两 个 


HTTP 处 理 阶 段 


*/ 
*h = ngx_http_realip_handler,; 
return NGX_OK， 

} 


通过 这 个 例子 可 以 看 到 怎样 在 NGX_HTTP POST READ PHASE 
或 者 NGX_HTTP PREACCESS_PHASE 阶 段 添 加 HTTP 模 块 。 


10.6.3 NGX HTTP SERVER _ REWRITE _ PHASE 阶段 


NGX_HTTP_SERVER_REWRITE_PHASE 阶 段 的 checker 方 法 是 
ngX_http_core_rewrite_phase。 表 10-2 总 结 了 该 阶段 下 
ngx_http_handler_pt 处 理 方 法 的 返回 值 是 如 何 影 响 HTTP 框 染 执 行 的 ， 注 
意 ， 这 个 阶段 中 不 存在 返回 值 可 以 使 请 求 直 接 跳 到 下 一 个 阶段 执行 。 


表 10-2 NGX_HTTP_SERVER_REWRITE_PHASE 、 
NGX_HTTP_REWRITE_PHASE 阶 段 站 HTTP 模 块 的 ngx_http_handler_pt 
方法 返回 值 意义 


中 


返回 值 总 类 


Ri 当前 的 ngx_http_handler_pt 处 理 方法 尚未 结束 ， 这 意味 着 该 处 理 方 法 在 当前 阶段 中 有 机 会 
一 再 次 被 调用 

NGx DECLINED 当前 ngx_http_handler_pt 处 理 方法 执行 完毕 ， 按 照 顺序 执行 下 一 个 ngx_http_ handler pt 处 
后 理 方法 

NGX AGAIN 

NGX _ DONE oe pi 

a 需要 调用 ngx_http_finalize_request 结束 请 求 

其 他 


官方 提供 的 ngx_http_rewrite_module 模 块 定义 了 
ngx_http_rewrite_handler 方 法 ， 同 时 将 它 添加 a 到 了 
NGX_HTTP_SERVER_REWRITE_PHASE 和 
NGX_HTTP_REWRITE_PHASE 阶 段 ， 这 里 就 不 再 列举 其 代码 了 。 


10.6.4 NGX HTTP FIND _CONFIG PHASE 阶段 


NGX_HTTP_FIND_CONFIG_PHASE 是 一 个 关键 阶段 ， 这 个 阶段 
是 不 可 以 跳 过 的 ， 也 就 是 说 ， 在 ngx_http_phase_engine_t 中 ， 人 处 理 方法 
组 成 的 数组 必然 要 有 阶段 的 处 理 方法 ， 因 为 这 是 HTTP 框 架 基 于 location 
设计 的 基石 。 


HTTP 框 架 提 供 了 ngx_http_core_find_config_phase 方 法 用 于 执行 这 
一 步 台 ， 也 就 是 说 ， 任 何 HTTP 模 块 不 可 以 同 这 一 阶段 中 添加 处 理 方法 
(添加 了 也 是 无 效 的 ) !ngx_http_core_find_config_phase 方 法 实际 上 就 
是 根据 NGX_HTTP_SERVER_REWRITE_PHASE 步 又 重 写 后 的 URI 检 索 


出 匹配 的 location 块 的 ， 其 原理 为 从 location 组 成 的 静态 二 又 查找 树 中 快 


速 检索 ， 具 体 可 参照 10.5 节 。 


10.6.5 NGX_HTTP_REWRITE_PHASE 阶 段 


NGX HTTP FIND_ CONEFIG_PHASE 阶 段 检索 到 location 后 有 机 会 
再 次 利用 rewrite 〈 重 写 ) URL， 这 一 工作 就 是 在 
NGX _ HTTP REWRITE_PHASE 阶 段 完 成 的 。 


NGX_HTTP_REWRITE_PHASE 阶 段 与 10.6.3 节 中 的 
NGX_HTTP_SERVER_REWRITE_PHASE 阶 段 几 乎 是 完全 相同 的 ， 它 
们 的 checker 方 法 都 是 ngx_http_core_rewrite_phase， 在 这 一 阶段 中 ， 
ngx_http_handler_pt 方 法 的 返回 值 意义 与 表 10-2 也 是 完全 相同 的 ， 不 再 


10.6.6 NGX HTTP POST REWRITE _ PHASE 阶段 


NGX_HTTP POST_REWRITE _ PHASE 阶段 就 像 
NGX_HTTP FIND_CONFIG_PHASE 阶 段 一 样 ， 只 能 由 HTTP 框 架 实 
现 ， 不 允许 HTTP 模 块 向 该 阶段 添加 ngx_http_handler_pt 处 理 方法 。 


NGX_HTTP POST_REWRITE _ PHASE 阶段 的 checker 方 法 是 


ngx_http_core_post_rewrite_phase， 它 的 意义 在 于 检查 rewrite 重 写 URL 的 


次 数 不 可 以 超过 10 次 ， 以 此 防止 由 于 rewrite 死 循环 而 造成 整个 Nginx 服 
务 都 不 可 用 。 


10.6.7 NGX HTTP PREACCESS _ PHASE 阶段 


NGX_HTTP PREACCESS_PHASE 阶 段 一 般 用 于 对 当前 请 求 进行 
限制 性 处 理 ， 它 的 checker 方 法 与 10.6.1 节 中 详细 描述 过 的 
ngx_http_core_generic_phase 方 法 一 样 ， 因 此 ， 在 这 一 阶段 中 执行 的 
ngx_http_handler_pt 处 理 方法 ， 其 返回 值 意义 也 与 表 10-1 是 完全 相同 
的 ， 不 再 芍 述 。 


10.6.8 NGX HTTP_ACCESS _ PHASE 阶段 


NGX_HTTP_ACCESS_PHASE 阶 段 与 
NGX_HTTP PREACCESS_PHASE 阶 段 大 不 相同 ， 这 主要 体现 在 它 的 
checker 方 法 是 ngx_http_core_access_phase 上 ， 这 也 就 致使 在 
NGX_HTTP_ACCESS_PHASE 阶 段 ngx_http_handler_pt 处 理 方法 的 返回 
值 有 了 新 的 意义 ， 见 表 10-3。 


表 10-3 NGX HTTP ACCESS _ PHASE 阶段 下 HTTP 模 块 的 
ngx_http_handler_pt 方 法 返回 值 意 义 


返回 值 


NGX_OK 


NGX_ DECLINED 
NGX AGAIN 


NGX DONE 


NGX HTTP FORBIDDEN 


NGX HTTP UNAUTHORIZED 


NGX ERROR 
其 他 


如 果 在 nginx.conf 中 配置 了 satisfy all， 那 么 将 按照 顺序 执行 下 一 个 ngx_ 
http_ handler pt 处 理 方法 ; 如 果 在 nginx.conf 中 配置 了 satisfy any， 那么 将 执 
行 下 一 个 ngx_http_phases 阶段 中 的 第 一 个 ngx_http_ handler pt 处 理 方法 

按照 顺序 执行 下 一 个 ngx_http_ handler pt 处 理 方 法 

当前 的 ngx_http handler pt 处 理 方法 尚未 结束 ， 这 意味 着 该 处 理 方法 在 当前 
阶段 中 有 机 会 再 次 被 调用 。 这 时 会 把 控制 权 交还 给 事件 模块 ， 下 次 可 写 事件 
发 生 时 会 再 次 执行 到 该 ngx_http handler pt 处 理 方法 

如 果 在 nginx.conf 中 配置 了 satisfy any， 那 么 将 ngx http request t 中 的 
access_code 成 员 设 为 返回 值 ， 按 照 顺 序 执行 下 一 个 ngx_http_handler pt 处 
理 方法 ; 如 果 在 nginx.conf 中 配置 了 satisfy all， 那 么 调用 ngx_http_finalize_ 
request 结束 请 求 


需要 调用 ngx_http_finalize_request 结束 请 求 


从 表 10-3 中 可 以 看 出 ，NGX_HTTP_ACCESS_PHASE 阶 段 实际 上 
与 nginx.conf 配 置 文件 中 的 satisfy 配 置 项 有 紧密 的 联系 ， 所 以 ， 任 何 介 
入 NGX_HTTP_ACCESS_PHASE 阶 段 的 HTTP 模 块 ， 在 实现 
ngx_http_handler_pt 方 法 时 都 需要 注意 satisfy 的 参数 ， 该 参数 可 以 由 
ngx_http_core_loc_conf t 结 构 体 中 得 到 。 


typedef struct ngx_http_core_ loc conf_s ngx_http_core_ loc conf_t; 


struct ngx_http_core_loc conf_s { 


// 仅 可 以 取 值 为 


NGX_HTTP_SATISFY_ALL 或 者 


NGX_HTTP_SATISFY_ANY 
ngx_uint_t satisfy; 


}; 


如 果 不 根据 所 在 location 中 的 satisfy 参 数 来 决定 返回 值 ， 那 么 可 能 造 


成 未 知 结果 。 


10.6.9 NGX HTTP POST _ ACCESS _ PHASE 阶段 


NGX_HTTP POST_ACCESS_PHASE 阶 段 又 是 一 个 只 能 由 HTTP 框 
架 实 现 的 阶段 ， 不 允许 HTTP 模 块 向 该 阶段 添加 ngx_http_handler_pt 处 理 
方法 。 这 个 阶段 完全 是 为 之 前 的 NGX_HTTP_ACCESS_PHASE 阶 段 服 
务 的 ， 换 句 话 说 ， 如 果 没 有 任何 HTTP 模 块 介入 
NGX_HTTP_ACCESS_PHASE 阶 段 处 理 请 求 ， 


NGX_ HTTP POST ACCESS _PHASE 阶 段 就 不 会 存在 。 


NGX HTTP POST_ACCESS_ PHASE 阶 段 的 checker 方 法 是 


As 


ngX_http_core_post_access_phase， 它 的 工作 非常 简单 ， 束 是 检查 
ngx_http_request_t 请 求 中 的 access_code 成 员 ， 当 其 不 为 0O 时 就 结束 请 求 

(表示 没有 访问 权限 ) ， 否 则 继续 执行 下 一 个 ngx_http_handler_pt 处 理 
pa 


10.6.10 NGX_HTTP_ TRY_FILES_PHASE 阶 段 


NGX_HTTP TRY _ FILES_ PHASE 阶 段 也 是 一 个 只 能 由 HTTP 框 架 
实现 的 阶段 ， 不 允许 HTTP 模 块 向 该 阶段 添加 ngx_http_handler_pt 处 理 方 
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NGX_ HTTP TRY _FILES PHASE 阶段 的 checker 方 法 是 


ngx_http_core_try_files_phase， 它 是 与 nginx.conf 中 的 try_files 配 置 项 密 


切 相 关 的 ， 如 果 try_files 后 指定 的 静态 文件 资源 中 有 一 个 可 以 访问 ， 这 
时 就 会 直接 读 取 文 件 并 发 送 响 应 给 用 户 ， 不 会 再 向 下 执行 后 续 的 阶 
段 ， 如 果 所 有 的 静态 文件 资源 都 无 法 执行 ， 将 会 继续 执行 
ngx_http_phase_engine_t 中 的 下 一 个 ngx_http_handler_pt 处 理 方法 。 


10.6.11 NGX_HTTP_CONTENT_PHASE 阶 段 


这 是 一 个 核心 HTTP 阶 段 ， 可 以 说 大 部 分 HTTP 模块 都 会 在 此 阶段 
重新 定义 Nginx 服 务 句 的 行为 ， 如 第 3 章 中 提 到 的 mytest 模 块 。 
NGX_HTTP_CONTENT_PHASE 阶 段 之 所 以 被 众多 HTTP 模 块 “钟爱 ”， 
主要 基于 以 下 两 个 原因 : 


其 一 ， 以 上 9 个 阶段 主要 专注 于 4 件 基 础 性 工作 : rewrite 重 写 URL 、 
找到 location 配 置 块 、 判 断 请 求 是 否 具备 访问 权限 、try_files 功 能 优先 读 
取 静 态 资 源 文件 ， 这 4 个 工作 通常 适用 于 绝 大 部 分 请 求 ， 因 此 ， 许 多 
HTTP 模 块 希望 可 以 共享 这 9 个 阶段 中 已 经 完成 的 功能 。 


其 二 ，NGX_HTTP_CONTENT_PHASE 阶 段 与 其 他 阶段 都 不 相同 
的 是 ， 它 向 HITP 模 块 提供 了 两 种 介入 该 阶段 的 方式 : 第 一 种 与 其 他 10 
个 阶段 一 样 ， 通 过 向 全 局 的 ngx_http_core_main_conf t 结 构 体 的 phases 
数组 中 添加 ngx_http_handler_ pt 处理 方法 来 实现 ， 而 第 二 种 是 本 阶段 独 
有 的 ， 把 希望 处 理 请 求 的 ngx_http_handler_pt 方 法 设置 到 location 相 关 的 


ngx_http_core_loc_conf t 结 构 体 的 handler 指 针 中 ， 这 正 是 第 3 章 中 mytest 
例子 的 用 法 。 


上 面 所 说 的 第 一 种 方式 ， 也 是 HTTP 模 块 介 入 其 他 10 个 阶段 的 唯一 
方式 ， 是 通过 在 必定 会 被 调用 的 postconfiguration 方 法 向 全 局 的 


ngx_http_core_main_conf t 结 构 体 的 


phases[INGX_HTTP_CONTENT_PHASE] 动 态 数 组 添加 
ngx_http_handler_pt 处 理 方法 来 达成 的 ， 这 个 处 理 方法 将 会 应 用 于 全 部 
的 HTTP 请 求 。 


而 第 二 种 方式 是 通过 设置 ngx_http_core_loc_conf t 结 构 体 的 handler 
指针 来 实现 的 ， 在 10.2.3 节 中 我 们 已 经 知道 ， 每 一 个 location 都 对 应 着 一 
个 独立 的 ngx_http_core_loc_conf t 结 构 体 。 这 样 ， 我 们 就 不 必 在 必定 会 
被 调用 的 postconfiguration 方 法 中 添加 ngx_http_handler_pt 处 理 方 法 了 ， 
而 可 以 选择 在 ngx_command_t 的 某 个 配置 项 (如 第 3 章 中 的 mytest 配 置 
项 ) 的 回调 方法 中 添加 处 理 方法 ， 将 当前 location 块 所 属 的 
ngx_http_core_loc_conf t 结 构 体 中 的 handler 设 置 为 ngx_http_handler_pt 处 
理 方法 。 这 样 做 的 好 处 是 ，ngx_http_handler_pt 处 理 方法 不 再 应 用 于 所 
有 的 HTTP 请 求 ， 仅 仅 当 用 户 请 求 的 URI 匹 配 了 location 时 (也 就 是 
mytest 配 置 项 所 在 的 location) 才 会 被 调用 。 这 也 就 意味 着 它 是 一 种 完 
全 不 同 于 其 他 阶段 的 使 用 方式 。 


此 ， 当 HTTP 模 块 实现 了 某 个 ngx_http_handler_pt 处 理 方法 并 希望 
介入 NGX_HTTP_ CONTENT PHASE 阶段 来 处 理 用 户 请 求 时 ， 如 果 和 希 
望 这 个 ngx_http_handler_ pt 方法 应 用 于 所 有 的 用 户 请 求 ， 则 应 该 在 
ngx_http_module_t 接 口 的 postconfiguration 方 法 中 ， 癌 
ngx_http_core_main_conf t 结 构 体 的 
phases[INGX_HTTP_CONTENT_PHASE] 动 态 数 组 中 添加 
ngX_http_handler_pt 处 理 方法 ; 反之 ， 如 果 硕 望 这 个 方式 仅 应 用 于 URI 
匹配 了 某 些 ]ocation 的 用 户 请 求 ， 则 应 该 在 一 个 location 下 配置 项 的 回调 
方法 中 ， 把 ngx_http_handler_pt 方 法 设置 到 ngx_http_core loc_conf t 结 构 
体 的 handler 中 。 


@ 注意 ”ngx_http_core_loc_conf t 结 构 体 中 仅 有 一 个 handler 指 
针 ， 它 不 是 数组 ， 这 也 就 意味 着 如 果 采 用 上 述 的 第 二 种 方法 添加 
ngx_http_handler_ pt 处理 方 法， 那么 每 个 请 求 在 
NGX_HTTP_ CONTENT PHASE 阶段 只 能 有 一 个 ngx_http_handler_pt 处 
理 方 法 。 而 使 用 第 一 种 方法 时 是 没有 这 个 限制 的 ， 
NGX_HTTP_CONTENT_PHASE 阶 段 可 以 经 由 任意 个 HTTP 模 块 处 理 。 


当 同 时 使 用 这 两 种 方式 设置 hgx_http_handler_pt 处 理 方法 时 ， 只 有 
第 二 种 方式 设置 的 ngx_http_handler_pt 处 理 方法 才 会 生效 ， 也 就 是 设置 
handler 指 针 的 方式 优先 级 更 高 ， 而 第 一 种 方式 设置 的 
ngx_http_handler_ pt 处 理 方 法 将 不 会 生效。 如 采 一 个 location 配 置 块 内 有 


多 个 HTTP 模 块 的 配置 项 在 解析 过 程 都 试图 按照 第 二 种 方式 设置 
ngX_http_handler_pt 处 理 方法 ， 那 么 后 面 的 配置 项 将 有 可 能 覆盖 前 面 的 
配置 项 解析 时 对 handler 指 针 的 设置 。 


NGX_HTTP_CONTENT PHASE 阶段 的 checker 方 法 是 
ngX_http_core_content_phase。ngx_http_handler_pt 处 理 方法 的 返回 值 在 
以 上 两 种 方式 下 具备 了 不 同意 义 。 


在 第 一 种 方式 下 ，ngx_http_handler_pt 处 理 方法 无 论 返回 任何 值 ， 
都 会 直接 调用 ngx_http_finalize_request 方 法 结束 请 求 。 当 然 ， 
ngx_http_finalize_request 方 法 根据 返回 值 的 不 同 未 必 会 直接 结束 请 求 ， 


这 在 第 11 章 中 会 详细 介绍 。 


在 第 二 种 方式 下 ， 如 果 ngx_http_handler_pt 处 理 方法 返回 
NGX_DECLINED， 将 按 顺 序 向 后 执行 下 一 个 ngx_http_handler_pt 处 理 
方法 ;如果 返 回 其 他 值 ， 则 调用 ngx_http_finalize_request 方 法 结束 请 
求 o 


10.6.12 NGX HTTP LOG PHASE 阶段 


NGX_HTTP LOG_PHASE 阶 段 是 11 个 HTTP 处 理 阶 段 中 的 最 后 
个 ， 顾 名 思 义 ， 它 是 用 来 记录 日 志 的 ， 如 ngx_http_log_module 模 块 束 是 
在 这 一 阶段 中 记录 Nginx 访 问 日 志 的 。 如 果 希 望 在 请 求 的 最 后 阶段 做 一 


些 共性 的 收尾 工作 ， 不 妨 将 ngx_http_handler_pt 处 理 方法 添加 到 这 一 阶 
段 中 。 


NGX_HTTP LOG_PHASE 阶 段 的 checker 方 法 同样 是 
ngx_http_core_generic_phase， 因 此 ， 在 这 一 阶段 中 ， 
ngx_http_handler_ pt 处理 方法 的 返回 值 意义 与 表 10-1 是 完全 相同 的 。 


10.7 HTTP 框架 的 初始 化 流程 


本 市 将 综合 10.1 闻 ~10.6 广 的 内 容 ， 完 整地 介绍 HTTP 框 架 的 初始 
化 过 程 。 实 际 上 ， 这 个 初始 化 过 程 束 在 ngx_http_module 模 块 中 ， 当 配 
置 文 件 中 出 现 了 http{} 配 置 块 时 就 回调 ngx_http_block 方 法 ， 而 这 个 方 
法 吏 包 括 了 HTTP 框 架 的 完整 初始 化 流程 ， 如 图 10-10 所 示 。 


下 面 分 别 介绍 图 10-10 中 的 15 个 步骤 。 


1) 按照 在 ngx_modules 数 组 中 的 顺序 ， 由 0 开始 依次 递增 地 设置 所 
有 HTTP 模 块 的 ctx_index 字 段 。 这 个 字段 的 值 将 决定 HTTP 模 块 应 用 于 
请 求 时 的 顺序 。 


2) 第 2 步 ~ 第 7 步 实际 上 就 是 10.2.1 闻 中 描述 的 内 容 。 解 析 到 http{} 
块 时 产生 1 个 ngx_http_conf_ctx_t 结 构 体 ， 同 时 初始 化 它 的 main_conf 、 
srv_conf、loc_conf 3 个 指针 数组 ， 数 组 的 容量 就 是 第 1 步 中 获取 到 的 所 
有 HTTP 模 块 的 数量 。 


3) 依次 调用 所 有 HTTP 模 块 的 create_main _conf 方 法， 产生 的 配置 
结构 体 指 针 将 按照 各 模块 ctx_index 字 段 指 定 的 顺序 放 入 
ngx_http_conf_ctx_t 结 构 体 的 main_conf 数 组 中 。 


4) 依次 调用 所 有 HTTP 模 块 的 create_srv_conf 方 法 ， 产 生 的 配置 结 
构 体 指针 将 按照 各 模块 ctx_index 字 段 指定 的 顺序 放 入 
ngx_http_conf_ctx_t 结 构 体 的 Srv_conf 数 组 中 。 


5) 依次 调用 所 有 HTTP 模 块 的 create_loc_conf 方 法 ， 产 生 的 配置 结 
构 体 指针 将 按照 各 模块 ctx_index 字 上 段 指定 的 顺序 放 入 
ngx_http_conf_ctx_t 结 构 体 的 loc_conf 数 组 中 。 


6) 依次 调用 所 有 HTTP 模 块 的 preconfiguration 方 法 。 
7) 解析 http{} 块 下 的 main 级 别 配 置 项 。 


8) 依次 调用 所 有 HTTP 模 块 的 init_main_conf 方 法 。 


1 ) 初始 化 所 有 HTTP 
模块 的 ctx_index 序 号 


2) 分 配 解 析 main 级 别 配置 项 时 存放 
HTTP 模 块 结构 体 指针 的 3 个 数组 


3 ) 调 用 所 有 HTTP 
模块 的 create_main_conf 方法 


4) 调用 所 有 HTTP 
模块 的 create_srv_conf 方 法 


5) 调用 所 有 HTTP 
模块 的 create loc_conf 方 法 


6) 调 用 所 有 HTTP 
模块 的 preconfiguration 方 法 


7) 解析 http{} 
块 下 的 所 有 main 级 别 配 置 项 


8) 调用 所 有 HTTP 
模块 的 init_main_ conf 方 法 


9 ) 合并 main 、svr 、loc 级 别 下 
server 、location 相 关 的 配置 项 


10) 构造 location 


组 成 的 静态 二 叉 平衡 查找 树 


11) 初始 化 可 添加 处 理 方法 的 
7 个 HTTP 阶 段 的 动态 数组 


12) 调用 所 有 HTTP 模 块 的 
postconfiguration 方 法 使 之 可 以 介入 HTTP 阶 段 


13) 根据 各 HTTP 模 块 介入 的 处 理 方法 构造 出 
phase_engine handlers 数组 


14) 构造 server 
虚拟 主机 构成 的 支持 通配符 的 散 列 表 


15) 构造 监听 端口 与 server 
间 的 关联 关系 , 设置 新 连接 事件 的 回调 方法 


图 10-10 HTTP 框架 的 初始 化 流程 


@@ 注意 ”在 解析 main 级 别 配置 项 时 ， 如 果 遇 到 server(} 配 置 块 
将 会 触发 ngx_http_core_server 方 法 ， 并 开始 解析 server 级 别 下 的 配置 
项 ， 这 一 过 程 可 参见 10.2.2 广 。 在 解析 srv 级 别 配置 项 时 ， 如 有 果 侦 到 
location{} 配 置 块 ， 将 会 触发 ngx_http_core_location 方 法 ， 并 开始 解析 
location 级 别 下 的 配置 项 ， 这 一 过 程 可 参见 10.2.3T 。 


噶 


9) 调用 ngx_http_merge_servers 方 法 合并 配置 项 ， 这 一 步骤 的 内 
与 10.2.4 下 介绍 的 多 级 别 配 置 项 合并 是 一 致 的 。 


10) 按照 10.5 节 介绍 的 方式 ， 创 建 由 location 块 构造 的 静态 二 又 平 
衡 查找 树 。 


11) 在 10.6 节 中 我 们 介绍 过 ， 有 7 个 HTTP 阶 段 

(NGX_HTTP_POST_ READ PHASE 、 
NGX_HTTP_SERVER_REWRITE_PHASE 、 
NGX_HTTP_REWRITE_PHASE、 
NGX_HTTP_ PREACCESS_PHASE、NGX_HTTP_ACCESS_PHASE、 
NGX_HTTP_CONTENT_PHASE、NGX_HTTP LOG_PHASE) 是 允许 
任何 一 个 HTTP 模 块 实现 自己 的 ngx_http_handler_pt 处 理 方法 ， 并 将 其 
加 入 到 这 7 个 阶段 中 去 的 。 在 调用 HTTP 模 块 的 postconfiguration 方 法 癌 
这 7 个 阶段 中 添加 处 理 方法 前 ， 需 要 先 将 phases 数 组 中 这 7 个 阶段 里 的 


handlers 动 态 数 组 初始 化 (ngx_array_t 类 型 需要 执行 hgx_array_init 方 法 
初始 化 ) ， 在 这 一 步骤 中 ， 通 过 调用 ngx_http_init_phases 方 法 来 初始 


化 这 7 个 动态 数组 。 


12) 依次 调用 所 有 HTTP 模 块 的 postconfiguration 方 法 。HTTP 模 块 
可 以 在 这 一 步骤 中 将 目 己 的 ngx_http_handler_pt 处 理 方法 添加 到 以 上 7 
个 HTTP 阶 段 中 。 


13) 在 上 一 步 中 ， 各 HTTP 模 块 会 向 全 局 的 
ngx_http_core_main_conf t 结 构 体 中 的 phases 数 组 添加 处 理 方法 ， 该 数 
组 中 存在 11 个 成 员 ， 每 个 成 员 都 是 动态 数组 ， 可 能 包含 任何 数量 的 处 
理 方 法 。 这 一 步骤 将 遍历 以 上 所 有 处 理 方 法 ， 构 造 由 所 有 处 理 方法 构 
成 的 有 序 的 phase_engine.handlers 数 组 。 关 于 HTTP 阶 段 的 用 法 可 参见 
10.6 节 。 


14) 这 一 步骤 构造 server 虚 拟 主机 构成 的 文 持 通 配 符 的 散 列 表 ， 可 


参见 10.4 闻 的 内 容 。 


15) 这 一 步骤 构造 监听 端口 与 server 间 的 关联 关系 ， 设 置 新 连接 事 
件 的 回调 方法 为 ngx_http_init_connection， 可 参见 10.3T。 


以 上 15 个 步 又 就 是 HTTP 框 架 在 Nginx 的 启动 过 程 中 所 做 的 主要 工 
作 。 


10.8 4 


本 章 介绍 了 静态 的 HTTP 框 狠 ， 主 要 讨论 了 http 配 置 项 的 管理 与 合 
并 操作 ， 以 及 HTTP 框 架 怎 样 设计 server 和 ]ocation 的 数据 结构 以 期 快速 
选择 server 和 location 处 理 用 户 请 求 ， 监 听 地 址 是 如 何 与 server 天 联 赵 来 
的 ， 同 时 介绍 了 HTTP 的 11 个 处 理 阶 段 及 其 设计 原理 和 使 用 方法 。 通 过 
了 解 这 些 内 容 ， 读 者 可 以 从 HTTP 框架 的 角度 了 解 HITP 模 块 的 运行 机 
制 。 另 外 ， 本 章 扩展 了 第 3 章 中 介绍 的 单一 的 HITP 模 块 设 计 方法 ， 特 
别 是 根据 10.6 市 介绍 的 内 容 ， 可 以 设计 出 更 加 强大 的 HTTP 模 块 ， 深 入 
地 介入 到 任何 一 个 HTTP 处 理 阶段 中 。 


本 章 并 没有 涉及 HTTP 框 架 是 如 何 处 理 用 户 请 求 的 ，HTTP 框 架 的 
动态 处 理 流 程 将 在 第 11 章 中 介绍 。 


第 11 章 ”HTTP 框架 的 执行 流程 


本 草 将 介绍 动态 的 HTTP 框 架 ， 主 要 探讨 在 请 求 的 生命 周期 中 ， 基 
于 事件 驱动 的 HTTP 框 架 钙 怎样 处 理 网 络 事件 以 及 怎样 集成 各 个 HTTP 
模块 来 共同 处 理 HTTP 请 求 的 ， 同 时 ， 还 会 介绍 为 了 简化 HTTP 模 块 的 
开发 难度 而 提供 的 多 个 非 阻塞 的 异步 方法 。 本 章 内 容 与 第 9 章 介绍 的 事 
件 模 块 密切 相关 ， 同 时 还 会 使 用 到 第 10 章 介绍 过 的 http 配 置 项 和 11 个 阶 
段 。 另 外 ， 本 书 第 二 部 分 讲述 了 怎样 开发 HTTP 模 块 ， 本 章 将 会 回答 为 
什么 可 以 这 样 开 发 HTTP 模 块 。 


HTTP 框 架 存 在 的 主要 目的 有 两 个 : 


:Nginx 事 件 框 架 主要 是 针对 传输 层 的 TCP 的 ， 作 为 Web 服 务 器 
HTTP 模 块 需要 处 理 的 则 是 HTTP，HTTP 框 架 必 须要 针对 基于 TCP 的 事 
件 框架 解决 好 HTTP 的 网 络 传输 、 解 析 、 组 装 等 问题 。 


虽然 事件 驱动 架构 在 性 能 上 古 不 错 的 ， 但 它 的 开发 效率 并 不 高 ， 
而 HITP 模 块 的 业务 通 间 较 复 杂 ， 我 们 希望 HTTP 模块 在 拥有 事件 框 丸 
的 高 性 能 优势 的 同时 ， 尽 量 只 关注 业务 。 这 样 ，HTTP 框 以 殉 需 要 为 
HTTP 模 块 屏 蔽 事件 驱动 架构 ， 使 得 HTTP 模 块 不 需要 关心 网 络 事件 的 
处 理 ， 同 时 又 能 灵活 地 介入 那 11 个 阶段 中 以 处 理 请 求 。 


根据 以 上 HTTP 框 染 的 设计 目的 ， 我 们 再 来 看 HTTP 框 架 在 动态 执 
行 中 的 大 概 流程 : 先 与 客户 端 建立 TCP 连 接 ， 接 收 HTTP 请 求 行 、 头 部 
并 解析 出 它们 的 意义 ， 再 根据 nginx.conf 配 置 文件 找到 一 些 HTTP 模 
块 ， 使 其 依次 合作 着 处 理 这 个 请 求 。 同 时 为 了 简化 HTTP 模 块 的 开发 ， 
HTTP 框 架 还 提供 了 接收 HTTP 包 体 、 发 送 HTTP 响 应 、 派 生子 请 求 等 工 
具 和 方法 。 


对 于 TCP 网 络 事件 ， 可 粗略 地 分 为 可 读 事 件 和 可 写 事件 ， 然 而 可 
读 事件 中 又 可 细 分 为 收 到 SYN 包 带 来 的 新 连接 事件 、 收 到 FIN 包 融 来 
的 连接 关闭 事件 ， 以 及 套 接 字 缓 冲 区 上 真正 收 到 TCP 流 。 可 写 事件 虽 
然 相 对 简单 点 ， 但 Nginx 提 供 限制 速度 功能 ， 有 时 可 写 事件 触发 时 未 必 
可 以 去 发 送 响应 。 同 时 ， 为 了 精确 地 控制 超时 ， 还 需要 把 读 / 写 事件 放 
置 到 定时 絮 中 。 这 些 事 件 的 管理 都 需要 依靠 HTTP 框 染 ， 这 给 HTTP 框 
架 带 来 了 复杂 性 。 在 清楚 了 解 这 些 设计 后 ， 我 们 将 对 HTTP 模 块 的 开发 
有 一 个 非常 透彻 的 认识 ， 因 为 HTTP 模 块 完全 是 由 HTTP 框 架设 计 、 定 
义 的 ， 它 就 像 Android 应 用 程序 与 Android 操 作 系 统 间 的 关系 。 同 时 ， 
深入 了 解 HTTP 框 染 后 ， 读 者 会 明白 如 何 把 复杂 的 事件 驱动 机 制 从 关注 
于 业务 的 模块 中 分 离 ， 这 些 设计 方法 都 是 值得 读者 学 习 的 。 


11.1 HTTP 框架 执行 流程 概述 


本 章 在 介绍 HTTP 框 架 的 同时 会 说 明 它 怎样 使 用 事件 模块 提供 的 操 
作 方 法 ， 在 这 之 前 ， 先 来 回顾 一 下 第 9 章 中 关于 事件 驱动 模式 的 内 容 。 


每 一 个 事件 都 是 由 ngx_event_t 结 构 体 表示 的 ， 而 TCP 连 接 则 由 
ngx_connection_t 结 构 体 表示 ，HTTP 请 求 毫 无 疑问 是 基于 一 个 TCP 连 接 
实现 的 。 每 个 TCP 连 接 包 括 一 个 读 事 件 和 一 个 写 事 件 ， 它 们 放 在 
ngx_connection_t 中 的 read 成 员 和 write 成 员 中 。 通 过 事件 模块 提供 的 
ngx_handle_read_event 方 法 和 ngx_handle_write_event 方 法 ， 可 以 把 相应 
的 事件 添加 到 epoll 中 ， 我 们 可 以 期 待 在 满足 事件 触发 条 件 时 ，Nginx 进 
程 会 调用 ngx_event_t 事 件 的 handler 回 调 方法 执行 业务 。 而 通过 事件 模 
块 提 供 的 ngx_add_timer 方 法 可 以 将 上 面 的 读 事 件 或 者 写 事件 添加 到 定 
时 器 中 ， 在 满足 超时 条 件 后 ，Nginx 进 程 同样 会 调用 ngx_event_t 事 件 的 
handler 回 调 方法 执行 业务 。 


在 第 3 章 开 发 HITP 模 块 时 ， 并 没有 看 到 事件 模块 的 影子 ， 但 HTTP 
框架 确实 是 依靠 事件 驱动 机 制 实现 的 。 基 于 这 一 点 ， 先 来 总 结 一 下 
HTTP 框 架 需 要 完成 的 最 主要 的 4 项 工作 。 


HTTP 框 染 需 要 完成 的 第 一 项 工作 是 集成 事件 驱动 机 制 ， 管 理 用户 
发 起 的 TCP 连 接 ， 处 理 网 络 读 / 写 事件 ， 并 在 定时 万 中 处 理 请 求 超时 的 


事件 。 这 些 内 容 将 在 11.2 节 ~11.5 节 介绍 ， 其 中 11.2 节 会 讨论 新 连接 建 
立成 功 后 HTTP 框架 的 行为 ，11.3 节 介绍 第 一 个 网 络 可 读 事件 到 达 后 
HTTP 框 架 的 行为 ，11.4 广 介绍 在 没有 接收 到 完整 的 HTTP 请 求 行 之 前 
HTTP 框 架 所 要 完成 的 工作 ，11.5 闻 介绍 在 没有 接收 到 完整 的 HTTP 请 
求 尖 部 之 前 HTTP 框 架 所 要 完成 的 工作 。 


HTTP 框 染 需 要 完成 的 第 二 项 工作 是 与 各 个 HTTP 模 块 共同 处 理 请 
求 。 实 际 上 ， 通 过 第 3 章 的 例子 我 们 已 经 知道 ， 只 有 请 求 的 URI 与 
location 配 置 匹 配 后 HTTP 框 架 才 会 调度 HTTP 模 块 处 理 请 求 。 而 在 第 10 
章 中 也 已 看 到 ，HTTP 框 架 定义 了 11 个 阶段 ， 其 中 4 个 基本 的 阶段 只 能 
由 HTTP 框 架 处 理 ， 其 余 的 7 个 阶段 可 以 让 各 HTTP 模 块 介入 来 共同 处 理 
请 求 。 因 此 ，HTTP 框 架 需 要 在 这 7 个 阶段 中 调度 合适 的 HTTP 模 块 处 理 
请 求 。 第 11.6 节 中 将 介绍 HITP 框 以 如 何 调度 HTTP 模 块 参与 到 请 求 的 
处 理 中 。 


第 三 项 工作 与 第 5 章 介 绍 过 的 subrequest 功 能 有 关 。 为 了 实现 复杂 
的 业务 ，HTTP 框 以 允许 将 一 个 请 求 分 解 为 多 个 子 请 求 ， 当 然 ， 于 请 求 
还 可 以 继续 向 下 派生 “孙子 ”请 求 ， 这 样 束 可 以 把 复 洒 的 功能 分 散 到 多 
个 子 请 求 中 ， 每 个 子 请 求 仅 专注 于 一 个 功能 。 这 种 设计 也 是 一 种 平 
衡 ， 使 用 事件 驱动 机 制 在 提高 性 能 的 同时 其 实 大 大 增加 了 程序 的 复杂 
度 ， 特 别 是 开发 复杂 功能 时 太 多 事件 的 处 理会 让 代码 混乱 不 起 ， 而 子 


请 求 的 派生 则 可 以 降低 复杂 度 ， 使 得 Nginx 可 以 提供 多 样 化 的 功能 。 在 


第 11.7 闻 中 ， 将 讨论 HTTP 框 染 是 如 何 设 计 、 实 现 subrequest 功 能 的 。 


HTTP 框 架 的 第 四 项 工作 则 是 提供 基本 的 工具 接口 ， 供 各 HTTP 模 

块 使 用 ， 诸 如 接收 HTTP 包 体 ， 以 及 发 送 HITP 响 应 头 部 、 响 应 包 体 

等 。 在 11.8 攻 中 将 说 明 HITP 框 钦 提 供 的 接收 HTTP 包 体 功能 ，11.9 有 将 
说 明 发 送 HTTP 啊 应 是 怎样 实现 的 ， 在 11.10 市 中 将 讨论 如 何 结束 HTTP 
请 求 。 为 什么 要 专门 讨论 请 求 的 结束 呢 ? 因为 在 基于 事件 驱动 的 HTTP 
框架 中 ， 由 于 每 个 HTTP 模 块 仅 能 在 某 一 时 刻 介 入 到 请 求 中 ， 所 以 有 时 
候 它 需要 表达 一 种 希望 “ 延 后 ”结束 请 求 的 意思 ， 这 一 特性 造成 了 结 

请 求 的 动作 十 分 复杂 ， 因 而 使 用 独立 的 一 节 来 专门 说 明 。 


本 章 的 全 部 内 容 就 是 在 探讨 如 何 完成 以 上 四 项 工作 。 


11.2 ”新 连 授 建立 时 的 行为 


当 Nginx 接 收 到 用 户 发 起 TCP 连 接 的 请 求 时 ， 事 件 框架 将 会 负责 把 
TCP 连 接 建 立 起来， 如 果 TCP 连 接 成 功 建立 ，HTTP 框 染 就 会 介入 请 求 
的 处 理 了 ， 如 图 9-5 所 示 ， 在 ngx_event_accept 方 法 建立 新 连接 的 最 后 1 
步 ， 将 会 调用 ngx_listening_t 监 昕 结构 体 的 handler 方 法 。 在 10.3 节 中 讲 
过 ，HTTP 框 染 在 初始 化 时 就 会 将 每 个 监 昕 ngx_listening_t 结 构 体 的 
handler 方 法 设 为 ngx_http_init_connection 方 法 ， 如 下 所 示 。 


void ngx_http_init_ connection(ngx_connection t *c) 


即 HTTP 框 染 处 理 请 求 的 第 一 步 束 在 ngx_http_init_connection 方 法 
中 ， 这 里 传 入 的 参数 c 束 是 新 建立 的 连接 。 图 11-1 列 举 了 
ngx_http_init_ connection 方 法 所 做 的 主要 工作 。 


设置 可 读 事 全 
的 回调 方法 
[ 检 查 是 否 有 可 读 的 TCP 尝 | 


[未 接收 到 TCP 流 ] 


[接收 到 TCP 流 ] 


2 ) 执行 ngx_http_init_request 


初始 化 请 求 并 处 理 TCP 流 


3 ) 将 可 读 事 件 加 入 到 定时 震中 以 
监控 接收 请 求 是 - 否 超 时 


4) 将 可 读 事 件 加 入 到 


)0j 中 


多 


图 11-1 建立 连接 成 功 后 HTTP 框 架 的 行为 


下 面 简单 解释 一 下 图 11-1 中 的 4 个 步 又 : 


1) 将 新 建立 的 连接 c 的 可 读 事件 处 理 方法 设置 为 
ngx_http_init request。 在 9.3 世 我 们 介绍 过 ngx_connection_t 结 构 体 中 会 
用 read 成 员 表 示 连 接 上 的 可 读 事件 ，write 成 员 表 示 可 写 事件 。 读 / 写 事 
件 均 使 用 ngx_event_t 结 构 体 表示 。 在 9.2 节 中 又 介绍 过 每 个 事件 发 生 时 
事件 框架 都 会 调用 其 中 的 handler 方 法 。 这 一 步骤 实际 上 就 是 把 连接 c 的 
read 读 事件 的 handler 方 法 设 为 ngx_http_init_request， 它 意味 着 当 用 户 在 
这 个 TCP 连 接 上 发 送 的 数据 到 达 服 务 器 后 ，ngx_http_init_request 方 法 
将 会 被 调用 〈 参 见 11.3 贡 ) 


事实 上 ， 对 于 可 写 事件 ， 也 会 设置 它 的 handler 回 调 方 法 为 
ngx_http_empty_handler， 这 个 方法 不 会 做 任何 工作 ， 如 下 所 示 。 


void ngx_http_empty_handler(ngx_event_t *wev) 


ngx_log_debug0O(NGX_LOG_ DEBUG_HTTP, wev->l0g, 0, "http empty handler"); 
return,; 


} 


这 个 方法 仅 有 一 个 用 途 : 当 业 务 上 不 需要 处 理 可 写 事件 时 ， 残 把 
ngx_http_empty_handler 方 法 设置 到 连接 的 可 写 事件 的 handler 中 ， 这 样 
可 写 事件 被 定时 器 或 者 epoll 触 发 后 是 不 做 任何 工作 的 。 


@ 注意 ”下面 会 多 次 使 用 ngx_http_empty_handler 方 法 。 


2) 如 果 新 连接 的 读 事 件 ngx_event_t 结 构 体 中 的 标志 位 ready 为 1， 
实际 上 表示 这 个 连接 对 应 的 套 接 字 缓 存 上 已 经 有 用 户 发 来 的 数据 ， 这 


时 束 可 调用 上 面 说 过 的 ngx_http_init request 方法 处 理 请 求 ， 参 见 11.3 


十 上 


加 区 | O 


3) 在 9.7.3 节 的 表 9-5 中 我 们 介绍 过 定时 吉 的 用 法 ， 在 这 一 步骤 中 
将 调用 ngx_add_timer 方 法 把 读 事件 添加 到 定时 器 中 ， 设 置 的 超时 时 间 
则 是 nginx.conf 中 client_header_timeout 配 置 项 指定 的 参数 。 也 残 是 说 ， 
如 有 条 经 过 client_header_timeout 时 间 后 这 个 连接 上 还 没有 用 户 数据 到 
达 ， 则 会 由 定时 句 触 发 调用 读 事件 的 ngx_http_init request 处理 方 法 。 


4) 我 们 在 9.2.1 节 中 介绍 过 ngx_handle_read_event 方 法 ， 它 可 以 将 
一 个 事件 添加 到 epoll 中 。 在 这 一 步骤 中 ， 将 调用 
ngx_handle_read_event 方 法 把 连接 c 的 可 读 事件 添加 到 epoll 中 。 注 意 ， 
这 里 并 没有 把 可 写 事件 添加 到 epoll 中 ， 因 为 现在 不 需要 向 客户 端 发 送 
任何 数据 。 


以 上 4 个 步 又 就 是 ngx_http_init_connection 方 法 的 主要 工作 ， 也 整 
是 新 连接 建立 成 功 时 HTTP 框 架 对 请 求 的 处 理 。 


11.3 ”第 一 次 可 该 事件 的 处 理 


当 TCP 连 接 上 人 第 一 次 出 现 可 读 事件 时 ， 将 会 调用 
ngx_http_init request 方法 初始 化 这 个 HTTP 请 求 ， 如 下 所 示 。 


static void ngx_http_init request(ngx_event_t *rev) 


实际 上 ，HTTP 框 架 并 不 会 在 连接 建立 成 功 后 就 开始 初始 化 请 求 
(参见 11.2 节 ) ， 而 是 在 这 个 连接 对 应 的 套 接 字 缓 促 区 上 确实 接收 到 了 
用 户 发 来 的 请 求 内 容 时 才 进 行 ， 这 种 设计 体现 了 Nginx 出 于 高 性 能 的 考 
虚 ， 这 样 减 少 了 无 谓 的 内 存 消耗 ， 降 低 了 一 个 请 求 占 用 内 存 资源 的 时 
间 。 因 此 ， 当 有 些 客户 端 建立 起 TCP 连 接 后 一 直 没 有 发 送 内 容 时 ， 
Nginx 是 不 会 为 它 分 配 内 存 的 。 


从 11.2 广 中 可 以 看 出 ， 在 有 些 情况 下 ， 当 TCP 连 接 建立 成 功 时 同时 
也 出 现 了 可 读 事件 〈 例 如， 在 套 接 字 设置 了 deferred 选 项 时 ， 内 核 仅 在 
套 接 字 上 确实 收 到 请 求 时 才 会 通知 epoll 调 度 事 件 的 回调 方法 ) ， 这 时 
ngXx_http_init request 方法 是 在 图 11-1 的 第 2 步 中 执行 的 。 当 然 ， 在 大 部 
分 情况 下 ，ngx_http_init request 方法 和 ngx_http_init_ connection 方 法 都 
是 由 两 个 事件 《ITCP 连 接 建 立成 功 事 件 和 连接 上 的 可 读 事 件 ) 触发 调用 
的 。 图 11-2 中 展示 了 在 ngx_http_init_ request 方法 中 究竟 做 了 哪些 工作 。 


[没有 超时 ] 
[已 经 超时 ] 


2) 构造 ngx_http_request_t 


结构 体 并 设置 到 连接 的 data 成 员 


3 ) 找 到 监听 地 址 对 应 
的 默认 server 


4) 设 置 这 个 请 求 对 应 的 
http 配 置 项 


5) 重新 设置 连接 读 事 件 的 回调 方法 为 


ngx_http_process_request_line 


6) 创建 接收 1 ) 调 用 ngx_http_close_connection 
缓冲 区 方法 关闭 连接 


7) 创 建 ngx_http_request_t 
结构 体 的 内 存 池 


8) 初始 化 ngx_http_request_t 
结构 体 中 的 容器 


9 ) 创 建 指针 数组 以 存放 所 有 HTTP 
模块 对 该 请 求 可 能 创建 的 上 下 文 结构 体 


10) 更 新 ngx_http_request_tt 
结构 体 的 请 求 开 始 时 间 


11) 调 用 ngx_http_process_requesLline 
接收 HTTP 请 求 行 


图 11-2 ”第 一 次 接收 到 可 读 事 件 后 的 行为 


从 图 11-2 中 可 以 看 出 ， 第 一 次 读 事 件 的 回调 方法 
ngx_http_init request 主要 做 了 3 件 事 : 对 请 求 构 造 ngx_http_request_t 结 
构 体 并 初始 化 部 分 参数 、 修 改 读 事件 的 回调 方法 为 
ngx_http_process_request_line 并 调用 该 方法 开始 接收 并 解析 HTTP 请 求 
行 。 下 面 详细 分 析 图 11-2 中 的 11 个 步 又 : 


1) 首先 回顾 一 下 图 11-1 的 第 3 步 ， 那 里 曾经 将 读 事件 也 添加 到 了 定 
时 恬 中 ， 超 时 时 间 就 是 配置 文件 中 的 client_header_timeout， 因 此 ， 首 
先 要 检查 读 事件 是 否 已 经 超时 ， 也 束 是 检查 ngx_event_t 事 件 的 timeout 
成 员 是 否 为 1。 如 果 timeout 为 1， 则 表示 接收 请 求 已 经 超时 ， 则 不 应 该 
继续 处 理 该 请 求 ， 于 是 调用 ngx_http_close_request 方 法 天 闭 请 求 ， 同 时 
由 ngx_http_init_request 方 法 中 返回 。ngx_http_close_request 方 法 的 详细 


介绍 可 参见 11.10.3 节 。 


2) 在 第 3 章 介 绍 HTTP 模 块 的 开发 时 曾 提 到 ， 每 个 请 求 都 会 有 一 个 
ngx_http_request_t 结 构 体 ， 所 有 的 HTTP 模 块 都 以 此 作为 核心 结构 体 来 
处 理 请 求 。 这 个 ngx_http_request_t 结 构 体 就 是 在 此 步骤 中 创建 的 ， 同 时 
还 将 这 个 关键 结构 体 的 地 址 存放 到 表示 TCP 连 接 的 ngx_connection_t 结 
构 体 中 的 data 成 员 上 。 这 一 步 中 还 会 把 表示 这 个 ngx_connection_t 结 构 体 
被 使 用 次 数 的 requests 成 员 加 1。11.3.1 节 将 会 详细 介绍 


ngx_http_request_t 结 构 体 。 


3) 从 10.3 节 可 以 看 出 ， 配 置 文件 的 每 个 server{} 块 中 都 可 以 针对 不 
同 的 本 机 IP 地 址 监听 同一 个 端口 ， 事 实 上 每 一 个 监听 对 象 
ngx_listening_t 都 会 对 应 着 监听 这 个 端口 的 所 有 监听 地 址 。 回 顾 一 下 
8.3.1 方 ，ngx_listening_t 结 构 体 中 有 一 个 servers 指 和 针 ， 在 HTTP 框 架 中 ， 
它 指向 监听 这 一 端口 的 所 有 监听 地 址 ， 而 每 个 监听 地 址 也 包含 了 其 所 
属 server 块 的 配置 项 ， 如 下 所 示 。 


typedef struct { 
ngx_http_core_srv_conf_t *default_ server; 


ngx_http_virtual names _t *virtual names; 
} ngx_http_addr_conf_t; 


default_server 也 就 是 这 个 监听 地 址 对 应 的 server 块 配置 信息 ， 在 第 
10 章 中 我 们 曾经 介绍 过 ngx_http_core_srv_conf t 结 构 体 是 如 何 管理 配置 
信息 的 。 这 一 步 中 将 会 遍历 ngx_listening t 结 构 体 的 servers 指 向 的 数 
组 ， 找 到 合适 的 监听 地 址 ， 然 后 找到 默认 的 server 庶 拟 主机 对 应 的 
ngx_http_core_srv_conf t 配 置 结构 体 。 


4) 在 第 2 步 建 立 好 的 ngx_http_request_t 结 构 体 中 ，main_conf 、 
srv_conf、loc_confj 文 3 个 成 员 表 示 这 个 请 求 对 应 的 main、srv、loc 级 别 
的 配置 项 ， 这 时 会 通过 刚刚 获取 到 的 默认 的 ngx_http_core_srv_conf _t 结 
构 体 设置 (10.2 节 中 介绍 过 ，ngx_http_core_srv_conf t 结 构 体 具有 一 个 
ngx_http_conf_ctx_t 类 型 的 成 员 ctx， 从 这 里 可 以 获取 到 3 个 级 别 的 配置 
项 指针 数组 ) 。 


5) 第 一 次 读 事 件 的 回调 方法 是 ngx_http_init_request， 它 仅 用 于 初 
台 化 请 求 ， 之 后 的 读 事 件 意味 着 接收 到 请 求 内 容 ， 显 而 易 见 ， 它 的 回 
调 方法 是 需要 改变 一 下 的 ， 即 在 这 一 步 中 将 把 这 个 读 事件 的 回调 方法 
设 为 ngx_http_process_request_line， 这 个 方法 将 会 负责 接收 并 解析 出 完 


整 的 HTTP 请 求 行 。 


6) 读 事件 被 触发 ， 其 实 就 意味 着 对 应 的 套 接 字 缓 冲 区 上 已 经 接收 
到 用 户 的 请 求 了 ， 这 时 需要 在 用 户 态 的 进程 空间 分 配 内 存 ， 用 来 把 内 
核 缓 冲 区 上 的 TCP 流 复制 到 用 户 态 的 内 存 中 ， 并 使 用 状态 机 来 解析 它 是 
否 是 合法 的 、 完 整 的 HTTP 请 求 。 这 一 步 将 在 ngx_connection_t 的 内 存 池 
中 分 配 一 块 内 存 (读者 可 以 思考 为 何 没 有 在 ngx_http_request_t 结 构 体 的 
内 存 池 中 分 配 接收 请 求 的 缓存 ) ， 内 存 块 的 大 小 与 nginx.conf 文 件 中 的 
client_header_buffer size 配置 项 参数 一 致 ，ngx_connection_t 结 构 体 的 
buffer 指 针 以 及 ngx_http_request_t 结 构 体 的 header_in 指 针 共 同 指向 这 块 
内 存 缓冲 区 。 这 个 header in 组 种 区 (除了 在 11.8.1 节 外 ) 将 负责 接收 用 
户 发 送 来 的 请 求 内 容 。 当 这 个 TCP 连 接 复 用 于 其 他 HTTP 请 求 时 ， 这 个 
buffer 指 针 指 向 的 内 存 仍然 是 可 用 的 ， 新 的 HTTP 请 求 初始 化 执行 到 这 
一 步 时 ， 束 不 用 再 次 由 ngx_connection_t 的 内 存 池 分 配 内 存 了 。 


7) ngx_http_request t 结 构 体 同样 有 一 个 内 存 池 ，HTTP 模 块 更 应 该 
在 ngx_http_request_t 结 构 体 的 pool 内 存 池上 申请 新 的 内 存 ， 这 样 请 求 结 
束 时 (连接 可 能 会 被 复 用 ) 该 内 存 池 中 分 配 的 内 存 都 会 及 时 回收 。 这 


一 步 中 将 会 创建 这 个 内 存 池 ， 内 存 池 的 初始 大 小 由 nginx.conf 文 件 中 的 
request_pool_size 配 置 项 参数 决定 。 这 个 内 存 池 只 会 在 11.10.2 世 中 介绍 


的 ngx_http_free_request 方 法 中 销毁 。 


8) 初始 化 ngx_http_request_t 结 构 体 中 的 部 分 容器 ， 如 headers_onut 
结构 体 中 的 ngx_list_t 类 型 的 headers 链 表 、variables 数 组 等 。 


9) 在 4.5 节 曾经 讲 过 ， 每 个 HTTP 模 块 都 可 以 针对 一 个 请 求 设置 上 
下 文 结构 体 ， 并 通过 ngx_http_set_ctx 和 和 ngx_http_get_module_ctx 宏 来 设 
置 和 获取 上 下 文 。 那 么 ， 这 些 HTTP 模 块 针对 请 求 设置 的 上 下 文 结构 体 
指针 ， 实 际 上 是 保存 到 ngx_http_request_t 结 构 体 的 ctx 指 针 数 组 中 的 。 
在 这 一 步骤 中 ， 会 分 配 一 个 具有 ngx_http_max_module (HTTP 模 块 的 总 
数 ) 个 成 员 的 指针 数组 ， 也 就 是 说 ， 为 每 个 HTTP 模 块 都 提供 一 个 位 置 
存放 上 下 文 结构 体 的 指针 。 


10) ngx_http_request_t 结 构 体 中 有 两 个 成 员 表 示 这 个 请 求 的 开始 处 
理 时 | 间 : start_sec 成 员 和 start_msec 成 员 。 这 一 步 中 将 会 初始 化 这 两 个 成 
员 。 在 11.9.2 节 中 将 会 看 到 这 两 个 成 员 的 用 法 ， 它 们 会 为 限 速 功能 服 


以 


11) 调用 ngx_http_process_request_line 方 法 开始 接收 、 解 析 HTTP 
请 求 行 。 


以 上 步骤 构成 了 ngx_http_init_reques 人 方法 的 主要 内 容 ， 其 中 构造 的 
ngx_http_request_t 结 构 体 在 接 下 来 的 小 节 中 会 详细 介绍 。 


从 第 3 章 开 始 ， 我 们 已 经 多 次 见 过 ngx_http_request_t 结 构 体 了 ， 但 
大 多 是 站 在 HTTP 模 块 的 角度 来 思考 如 何 使 用 Nginx 已 经 为 我 们 构造 好 
的 ngx_http_request_t 结 构 体 。 本 节 再 次 介绍 ngx_http_request_t 结 构 体 ， 
则 是 站 在 HTTP 框 架 的 角度 来 思考 如 何 完成 HTTP 框 架 的 基本 功能 。 下 
面 首先 说 明 它 与 HTTP 框 架 密切 相关 的 成 员 。 
typedef struct ngx_http_request_s ngx_http_request_t; 


struct ngx_http_request _s { 
// 这 个 请 求 对 应 的 客户 端 连接 


ngx_connection_t *connection; 


// 指向 存放 所 有 
HTTP 模 块 的 上 下 文 结构 体 的 指针 数组 


void **ctx; 


// 指向 请 求 对 应 的 存放 
main 级 别 配 置 结构 体 的 指针 数组 


void **main_conf; 


// 指向 请 求 对 应 的 存放 
srv 级 别 配置 结构 体 的 指针 数组 


void **srv_conf; 


// 指向 请 求 对 应 的 存放 
loc 级 别 配 置 结构 体 的 指针 数组 


void **]oc_conf; 


/* 在 接收 完 
HTTP 头 部 ， 第 一 次 在 业务 上 处 理 


HTTP 请 求 时 ， 


HTTP 框 架 提供 的 处 理 方法 是 


ngx_http_process_redquest。 但 如 果 该 方法 无 法 一 次 处 理 完 该 请 求 的 全 部 业务 ， 在 归还 


epol11 事 件 模块 后 ， 该 请 求 再 次 被 回调 时 ， 将 通 


ngx_http_request_handler 方 法 来 处 理 ， 而 这 个 方法 中 对 于 可 读 事 


read_event_handler 处 理 请 求 。 也 就 是 说 ， 


过 


HTTP 模 块 希望 在 底层 处 理 请 求 的 读 事 件 时 ， 重 新 实现 


read_event_handler 方 法 


*/ 


ngx_http_event_handler_pt read event_handler; 


a 


read_event_handler 回 


ngx_http_request_handler 方 法 判断 当前 事 


调 方法 类 似 ， 如 果 


FF 


事件 ， 


write_event_handler 处 理 请 求 。 


ngx_http_request_handler 的 流程 可 参见 


11-7*/ 


则 调用 


ngx_http_event_handler_pt write event_handler; 


// _ upstream 机制 


12 章 中 会 详细 说 明 


到 的 结构 体 ， 在 第 


ngx_http_upstream t *upstream; 
/* 表 示 这 个 请 求 的 内 存 池 ， 在 


ngx_http_free_request 方 法 中 销毁 。 它 与 


ngx_connection_t 中 的 内 存 池 意 义 不 同 ， 当 请 求 释 放 时 ， 


TCP 连 接 可 能 并 没有 关闭 ， 这 时 请 求 的 内 存 池 会 销毁 ， 但 


ngx_connection_t 的 内 存 池 并 不 会 销毁 


*/ 


ngx_pool _t *pool; 


// 用 于 接收 


HTTP 请 求 内 容 的 缓冲 区 ， 主 要 用 于 接收 


HTTP 头 部 


ngx_buf_t *header_in,; 


/*ngx_http_process_request_headers 方 法 在 接收 、 解 析 完 


HTTP 请 求 的 头 部 后 ， 会 把 解析 完 的 每 一 个 


HTTP 头 部 加 入 到 


headers_in 的 


headers 链 表 中 ， 同 时 会 构造 


的 处 到 


就 是 调 


3 


Ls 


二 
i 


判 权 到 


headers_in 中 的 其 他 成 员 


SS 
ngx_http_headers_in_t headers_in' 
/*HTTP 模 块 会 把 想 要 发 送 的 


HTTP 响 应 信息 放 到 
headers_out 中 ， 期 望 
HTTP 框 架 将 


headers_out 中 的 成 员 序 列 化 为 


HTTP 响 应 包 发 送 给 用 户 

*/ 
ngx_http_headers_ out_t headers_out 
// 接收 


HTTP 请 求 中 包 体 的 数据 结构 ， 详 见 


11;8 革 


ngx_http_request_body_t *request_body; 
// 延迟 关闭 连接 的 时 间 


time_t lingering_time; 
/* 当 前 请 求 初始 化 时 的 时 间 。 
start_sec 是 格林 威 治 时 间 


1970 年 


工 月 


1 日 竣 展 


0 点 


0 分 


秒 到 当前 时 间 的 秒 数 。 如 果 这 个 请 求 是 子 请 求 ， 则 该 时 间 是 子 请 求 的 生成 时 间 ; 如 果 这 个 请 求 是 用 


求 ， 则 是 在 建立 起 
TCP 连 接 后 ， 第 一 次 接收 到 可 读 事件 时 的 时 间 


*/ 
time_t start_sec; 
// 与 


start_sec 配 合 使 用 ， 表 示 相 对 于 


start_set 秒 的 毫秒 偏 移 量 


ngx_msec_t start_ msec; 
/* 以 下 


9 个 成 员 都 是 


户 发 来 的 请 


ngx_http_process_request_line 方 法 在 接收 、 解 析 


HTTP 请 求 行 时 解析 出 的 信息 ， 其 意义 在 第 


3 章 已 经 详细 描述 过 ， 这 里 不 再 介绍 


*/ 
ngx_uint_t method; 
ngx_uint_t http_version; 
ngx_str_t request_line; 
ngx_str_t uri; 
ngx_str_t args; 
ngx_str_t exten; 
ngx_str_t unparsed_uri; 
ngx_str_t method_name; 
ngx_str_t http_protocol,; 
/* 表 示 需 要 发 送 给 客户 端的 


HTTP 响 应 。 


out 中 保存 着 


headers_out 中 序列 化 后 的 表示 


HTTP 头 部 的 


TCP 流 。 在 调 


ngx_http_output_filter 方 法 后 ， 


out 中 还 会 保存 待 发 送 的 
HTTP 包 体 ， 它 是 实现 异步 发 送 


HTTP 响 应 的 关键 ， 参 见 


S 


11.9 节 
*/ 

ngx_chain_t *out; 

/* 当 前 请 求 既 可 能 是 用 户 发 来 的 请 求 ， 也 可 能 是 派生 出 的 子 请 求 ， 而 
main 则 标识 一 系列 相关 的 派生 子 请 求 的 原始 请 求 ， 我 们 一 般 可 通过 


main 和 当前 请 求 的 地 址 是 否 相 等 来 判断 当前 请 求 是 否 为 用 户 发 来 的 原始 请 求 


| 


yA 
ngx_http_request_t *main; 
// 当前 请 求 的 父 请 求 。 注 意 ， 父 请 求 未 必 是 原始 请 求 


ls 


ngx_http_request_t *parent; 
/* 与 


subrequest 子 请 求 相关 的 功能 。 在 
11.10.6 节 中 会 看 到 它们 在 


HTTP 框 架 中 的 部 分 使 用 方式 


*/ 


ngx_http_postponed_request_t *postponed ; 
ngx_http_post_subrequest_t *post_Ssubreduest 


/* 所 有 的 子 请 求 都 是 通过 


posted_requests 这 个 单 链 表 来 链接 起 来 的 ， 执 行 


post 子 请 求 时 调用 的 


I 

hr 

Ht 
i 


来 执行 子 请 求 的 


ngx_http_run_posted_requests 方 法 就 是 通过 遍历 该 


Ww 
ngx_http_posted request _t *posted requests,; 
/* 全 局 的 


ngx_http_phase_engine_t 结 构 体 中 定义 了 一 个 


ngx_http_phase_hand1ler_t 回 调 方法 组 成 的 数组 ， 而 


phase_handler 成 员 则 与 该 数组 配合 使 用 ， 表 示 请 求 下 次 应 当 执行 以 


phase_handler 作 为 序号 指定 的 数组 中 的 回调 方法 。 
HTTP 框 架 正 是 以 这 种 方式 把 各 个 
HTTP 模 块 集成 起 来 处 理 请 求 的 


%/ 
ngx_int_t phase_handler; 
/* 表 示 


NGX_HTTP_CONTENT_PHASE 阶 段 提供 给 


HTTP 模 块 处 理 请 求 的 一 种 方式 ， 


content_handler 指 向 


HTTP 模 块 实现 的 请 求 处 理 方 法 ， 详 见 


11.6.4 广 


* 
/ 
ngx_http_handler_pt content_handler; 
/* 在 


NGX_HTTP_ACCESS_PHASE 阶 段 需要 判断 请 求 是 否 具 有 访问 权限 时 ， 通 过 


access_code 来 传递 


HTTP 模 块 的 


handler 回 调 方法 的 返回 值 ， 如 果 


access_code 为 


9， 则 表示 请 求 具备 访问 权限 ， 反 之 则 说 明 请 求 不 具备 访问 权限 


*/ 
ngx_uint_t access_ code; 
// HTTP 请 求 的 全 部 长 度 ， 包 括 


HTTP 包 体 


off_t reduest_length 
/* 在 这 个 请 求 中 如 果 打 开 了 某 些 资源 ， 并 需要 在 请 求 结束 时 释放 ， 那 么 都 需要 在 把 定义 的 释放 资源 方法 添 
加 到 


cleanup 成 员 中 ， 详 见 


11.10.2 节 
*/ 
ngx_http_cleanup_t *cleanup; 
/* 表 示 当 前 请 求 的 引用 次 数 。 例 如 ， 在 使 
subrequest 功 能 时 ， 依 附 在 这 个 请 求 上 的 子 请 求 数目 


count 上 ， 每 增加 一 个 子 请 求 ， 


霸 


路 
. 


回 到 


count 数 就 要 加 
1。 其 中 任何 一 个 子 请 求 派 4 
main 指 针 指 向 的 请 求 ) 的 


tH 新 的 子 请 求 时 ， 对 应 的 原始 请 求 上 


nT 
lj 


count 值 都 要 加 
1。 又 如 ， 当 我 们 接收 
HTTP 包 体 时 ， 由 于 这 也 是 一 个 异步 调用 ， 所 以 


count 上 也 需要 加 


1， 这 样 在 结束 请 求 时 


11.10 节 中 介绍 ) ， 就 不 会 在 


count 引 用 计数 未 清 零 时 销毁 请 求 。 可 以 参见 


11.10.3 节 的 
ngx_http_close_request 方 法 
*/ 


unsigned count:8; 
// 阻塞 标志 位 ， 目 前 仅 


aio 使 用 ， 本 章 不 涉及 


unsigned blocked:8; 
// 标志 位 ， 为 


1 时 表示 当前 请 求 正 在 使 用 异步 文件 


unsigned aio:1; 
// 标志 位 ,为 


URL 发 生 过 


rewrite 重 写 


unsigned uri changed :1 
/* 表 示 使 


rewrite 重 写 


URL 的 次 数 。 因 为 目前 最 多 可 以 更 改 


10 次 ， 所 以 


uri_changes 初 始 化 为 


11， 而 每 重 写 


URL 一 次 就 把 


uri_changes 减 


le 


uri_changes 等 于 


9， 则 向 用 户 返 回 失败 


*/ 


unsigned uri_ changes:4; 
/* 标 志 位 ， 为 


1 时 表示 当前 请 求 是 


keepalive 请 求 


*/ 


unsigned keepalive:1,; 
/* 延 迟 关 闭 标志 位 ， 为 


1 时 表示 需要 延迟 关闭 。 例 如 ， 在 接收 完 
HTTP 头 部 时 如 果 发 现 包 体 存在 ， 该 标志 位 会 设 为 
141， 而 放弃 接收 包 体 时 则 会 设 为 


09， 参见 


11.8 节 
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unsigned lingering close:1; 
// 标志 位 ,为 


1 时 表示 正在 丢弃 


HTTP 请 求 中 的 包 体 


1 时 表示 请 求 的 当前 状态 是 在 做 内 部 跳 转 。 具 体 用 法 可 参见 图 


unsigned discard body:1; 
/* 标 志 位 ， 为 


11-5 中 的 第 


unsigned internal:1; 
/* 标 志 位 ， 为 


1 时 表示 发 送 给 客户 端的 


HTTP 响 应 头 部 已 经 发 送 。 在 调 


ngx_http_send_header 方 法 (参见 


11.9.1 节 ) 后 ， 若 已 经 成 功 地 局 动 响应 头 部 发 送 流程 ， 该 标志 位 就 会 置 为 
1， 用 来 防止 反复 地 发 送 头 部 
*/ 


unsigned header_sent:1; 
// 表示 缓冲 中 是 否 有 竺 发送 内 容 的 标志 位 


unsigned buffered:4; 


// 状态 机 解析 


HTTP 时 使 


state 来 表示 当前 的 解析 状态 


ngx_uint_t state 


以 上 介绍 的 ngx_http_request_t 结 构 体 成 员 ， 大 多 都 会 出 现在 本 章 后 
续 章 让 中 ， 读 者 在 看 到 相应 的 变量 时 可 及 时 回 到 本 他 查 询 其 意义 


11.4 接收 HTTP 请 求 行 


接收 HTTP 请 求 行 这 个 行为 必然 是 在 初始 化 请 求 之 后 发 生 的 。 在 图 
11-2 的 第 11 步 表明 已 经 调用 了 ngx_http_process_request_line 方 法 来 接收 
HTTP 请 求 行 。HTTP 请 求 行 的 格式 如 下 所 示 。 


GET /uri HTTP/1.1 


可 以 看 出 ， 这 样 的 请 求 行 长 度 是 不 定 的 ， 它 与 URI 长 度 相 关 ， 这 意 
味 着 在 读 事件 被 触发 时 ， 内 核 套 接 字 缓冲 区 的 大 小 未 必 足 够 搂 收 到 全 
部 的 HTTP 请 求 行 ， 由 此 可 以 得 出 结论 : 调用 一 次 
ngx_http_process_request_line 方 法 不 一 定 能 够 做 完 这 项 工作 。 所 以 ， 
ngx_http_process_request_line 方 法 也 会 作为 读 事 件 的 回调 方法 ， 它 可 能 
会 被 epoll 这 个 事件 驱动 机 制 多 次 调度 ， 反 复 地 接收 TCP 流 并 使 用 状态 机 
解析 它们 ， 直 到 确认 接收 到 了 完整 的 HTTP 请 求 行 ， 这 个 阶段 才 算 完 
成 ， 才 会 进入 下 一 个 阶段 接收 HTTP 头 部 。 


此 ，ngx_http_process_request_line 方 法 与 ngx_http_init_connection 
方法 、ngx_http_init_request 方 法 都 不 一 样 ， 后 两 种 方法 在 一 个 请 求 中 只 
会 被 调用 一 次 ， 而 ngxX_http_process_request_line 方 法 则 至 少 会 被 调用 一 
次 ， 而 到 展会 调用 多 少 次 则 取决 于 客户 端的 行为 及 网 络 中 卫 包 的 转发 
等 。 图 11-3 展 示 了 ngx_http_process_request_line 方 法 的 流程 ， 需 要 注意 


其 中 对 各 个 步骤 的 搞 述 ， 其 中 有 些 步 又 会 导致 
但 会 在 下 一 次 读 事 件 来 临 


ly 
a 


ngx_http_process_request_line 方 法 御 时 
时 继续 被 调用 。 


图 11-3 摘 述 了 ngx_http_process_request_line 方 法 的 主要 流程 ， 由 于 
它 涉 及 了 TCP 字 人 符 流 的 接收 、 解 机 ， 因 此 会 相对 复杂 一 些 ， 下 面 详细 描 


述 一 下 这 12 个 步骤 : 


1) 首先 检查 这 个 读 事件 是 否 已 经 超时 ， 超 时 时 间 仍 然 是 nginx.conf 
配置 文件 中 指定 的 client_header_timeout。 如 果 ngx_event_t 事 件 的 
timeout 标 志 为 1， 则 认为 接收 HTTP 请 求 已 经 超时 ， 调 用 
ngx_http_close_request 方 法 (参见 11.10.3 广 ) 关闭 请 求 ， 同 时 由 


ngx_http_process_request_line 方 法 中 返回 。 


2) 在 当前 读 事 件 未 超时 的 情况 下 ， 检 查 header_in 接 收 缓冲 区 ( 参 
见 图 11-2 的 第 6 步 ) 中 是 否 还 有 未 解析 的 字符 流 。 第 一 次 调用 
ngx_http_process_request_line 方 法 时 绥 冲 区 里 必然 是 空 的 ， 这 时 会 调用 
封闭 的 recv 方 法 把 Linux 内 核 套 搂 字 缓 神 区 中 的 TCP 流 复制 到 header_ ip 组 
冲 区 中 。header_ in 的 类 型 是 ngx_buf t， 它 的 pos 成 员 和 1last 成 员 指向 的 地 
址 之 间 的 内 存 束 古 接 收 到 的 还 未 解析 的 字符 流 。 如 果 header_in 授 收 缓 
冲 区 中 还 有 未 解析 的 字符 流 ， 则 不 会 调用 recv 方 法 接收 ， 而 是 跳 到 下 面 
的 第 4 步 继续 执行 。 


3) 在 第 2 步 中 曾经 调用 封装 的 recv 方 法 ， 如 果 返 回 值 表示 连接 出 现 
错误 或 者 客户 端 已 经 关闭 连接 ， 则 跳 转 到 第 1 步 ， 如 果 返 回 值 表示 接收 
到 客户 问 发 送 的 字符 流 ， 则 跳 转 到 第 5 步 中 解析 ;如 琳 返 回 值 表示 本 次 
没有 接收 到 TCP 流 ， 需 要 继续 检测 这 个 读 事件 ， 则 开始 本 步骤 的 执行 。 


目 先 检查 这 个 读 事件 是 否 在 定时 絮 中 ， 如 果 已 经 在 定时 器 ， 则 跳 
转 到 第 4 步 ， 反之， 调用 ngx_add_timer 方 法 向 定时 器 添加 这 个 读 事件 。 


4) 调用 ngx_handle_read_event 方 法 把 该 读 事件 添加 到 epoll 中 ， 同 


时 ngx_http_process_request_line 方 法 结束 。 


[检查 是 否 接收 HTTP 请 求 超时 ] 


[没有 超时 ] 


[接收 缓冲 区 中 没有 未 解析 的 数据 ] 


2) 在 缓冲 区 上 
接收 TCP 流 


[ 读 缓 冲 区 仍 有 空闲 ] ”[【 检 查 接收 方法 的 返回 值 ] 


[接收 缓冲 区 在 还 有 
未 解析 的 数据 ] 

RE bE | 

A [连接 错误 或 客户 端 关闭 连接 ] 


[如 果 已 经 接收 到 数据 ] [ 读 事 件 没有 在 定时 器 中 ] 


3) 将 读 事件 添加 
到 定时 器 中 


到 epoll 


5) 用 状态 机 解析 已 接收 
到 的 字符 流 
[检查 状态 机 的 返回 值 | 
[需要 继续 接收 数据 ] 


[ 读 缓冲 区 用 完 ] [解析 得 到 请 求 line] 


[解析 失败 ] 


7) 设 和 置 解析 成 功 的 1) 调用 ngx_http_close_request 
URI 等 参数 : 闭 请 求 


二 
下 > 


[HTTP 1.0 版 本 以 下 ] 
[HTTP10 或 者 HTTP1.1 版 本 ] 


10) 初始 化 存放 HTTP 
头 部 的 容器 


VY 
8 ) 找 到 请 求 对 应 的 


SeLIVeT 


11) 重新 设置 可 读 
事件 回调 方法 


12) 调用 Wi ee 
头 部 


process_request 


9) 调 用 ngx_http 
处 理 
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图 11-3 接收、 解析 HTTP 请 求 行 的 流程 图 


5) 在 第 2 步 接收 到 字符 流 后 ， 将 在 这 一 步骤 用 状态 机 解析 已 经 接 
收 到 的 TCP 字 符 流 ， 确 认 其 是 否 构成 完整 的 HITP 请 求 行 。 这 个 状态 机 
解析 请 求 行 的 方法 叫做 ngx_http_parse_request_line， 它 使 用 
ngx_http_request_t 结 构 体 中 的 state 成 员 来 保存 解析 状态 ， 如 下 所 示 。 


ngx_int_t ngx_http_parse_request_ line(ngx_http_request _t *r, ngx_buf_t *b) 


这 里 传 入 的 参数 b 是 header_in 绥 冲 区 ， 返 回 值 主要 有 3 类 : 返回 
NGX_OK 表 示 成 功 地 解析 到 完整 的 HTTP 请 求 行 ， 返回 NGX_AGAIN 表 
示 目 前 接收 到 的 字符 流 不 足以 构成 完成 的 请 求 行 ， 还 需要 接收 更 多 的 
字符 流 ; 返回 NGX_HTTP_PARSE_INVALID_REQUEST 或 者 
NGX_HTTP_PARSE_INVALID_09 METHOD 等 其 他 值 时 表示 接收 到 非 
法 的 请 求 行 。 


6) 如 果 ngx_http_parse_request_line 方 法 返回 NGX_OK， 表 示 成 功 
地 接收 到 完整 的 请 求 行 ， 这 时 跳 转 到 第 7 步 继续 执行 。 


如 果 ngx_http_parse_request_line 方 法 返回 NGX_AGAIN， 则 表示 需 
要 接收 更 多 的 字符 流 ， 这 时 需要 对 header_in 缓 冲 区 做 判断 ， 检 查 是 否 
还 有 空闲 的 内 存 ， 如 果 还 有 未 使 用 的 内 存 可 以 继续 接收 字符 流 ， 则 跳 
转 到 第 2 步 ， 检 查 缓冲 区 是 否 有 未 解析 的 字符 流 ， 否 则 调用 
ngx_http_alloc_large_header_buffer 方 法 分 配 更 大 的 接收 缓冲 区 。 到 底 分 


配 多 大 呢 ? 这 由 nginx.conf 文 件 中 的 large_client header_buffers 配 置 项 指 


定 。 


如 果 ngx_http_parse_request_line 方 法 返回 
NGX_HTTP_PARSE_INVALID_REQUEST 或 者 
NGX_HTTP_PARSE_INVALID_09_METHOD 等 其 他 值 ， 那 么 HTTP 框 
架 将 不 再 处 理 非法 请 求 ， 跳 转 到 第 1 步 关 闭 请 求 。 


7) 在 接收 到 完整 的 HTTP 请 求 行 后 ， 首 先 要 把 请 求 行 中 的 信息 如 
方法 名 、URI 及 其 参数 、HTTP 版 本 等 信息 设置 到 ngx_http_request_t 结 
构 体 的 相应 成 员 中 (如 request_line ~ uri、 method_name 、 unparsed_uri、 
http_protocol、exten、args 等 ) ， 在 3.6.2 节 开发 HTTP 模 块 时 曾 介绍 过 这 
些 成 员 的 用 法 ， 它 们 吏 是 在 这 一 步 中 被 赋值 的 。 


8) 如 果 在 第 7 步 得 到 的 http_version 成 员 中 显示 用 户 请 求 的 HTTP 版 
本 小 于 1.0 (如 HTTP 0.9 版 本 ) ， 其 处 理 过 程 将 与 HTTP 1.0 和 HTTP 1.1 
的 完全 不 同 ， 它 不 会 有 接收 HTTP 头 部 这 一 步骤 。 这 时 将 会 调用 
ngx_http_find_virtual_server 方 法 寻找 到 相应 的 虚拟 主机 ， 回 顾 一 下 在 
10.4 节 中 虚拟 主机 是 使 用 散 列表 来 进行 管理 的 ， 
ngx_http_find_virtual_server 方 法 就 是 用 于 在 散 列 表 中 检索 出 虚拟 主机 。 


如 果 http_version 成 员 中 显示 出 用 户 请 求 的 HTTP 版 本 是 1.0 或 者 更 高 
的 版 本 ， 则 直接 跳 到 第 10 步 中 执行 。 


9) 继续 处 理 HTTP 版 本 小 于 1.0 的 情形 。 由 于 不 需要 再 次 接收 HTTP 
头 部 ， 调 用 ngx_http_process_request 方 法 开始 处 理 请 求 (参见 11.6 


证 ) 


忆 


O 


10) 初始 化 ngx_http_request_t 结 构 体 中 存放 HTTP 头 部 的 一 些 容 
器 ， 如 headers_in 结 构 体 中 ngx_list_t 类 型 的 headers 链 表 容 器 、 
ngx_array_t 类 型 的 cookies 动 态 数 组 容 姨 等 ， 为 下 一 步 接 收 HTTP 头 部 做 
好 准备 (参见 11.5 节 ) 。 


11) 由 于 已 经 接收 完 HTTP 请 求 行 ， 因 此 这 时 把 读 事件 的 回调 方法 
由 ngx_http_process_request_line 改 为 ngx_http_process_request_headers, 


准备 接收 HTTP 头 部 。 


12) 调用 ngx_http_process_request_headers 方 法 开始 接收 HTTP 头 


11.5 ”接收 HTTP 头 部 


本 丰 将 描述 接收 HTTP 头 部 这 一 阶段 ， 该 阶段 是 通过 
ngx_http_process_request_headers 方 法 实现 的 ， 该 方法 将 被 设置 为 连接 
的 读 事件 回调 方法 ， 在 接收 较 大 的 HTTP 头 部 时 ， 它 有 可 能 会 被 反复 多 
次 地 调用 。HTTP 头 部 类 似 下 面 加 了 下 划 线 的 字符 串 ， 而 
ngx_http_process_request_headers 方 法 的 目的 就 在 于 接收 到 当前 请 求全 
部 的 HTTP 头 部 。 


GET /uri HTTP/1.1 
cred: xxx 
username: ttt 
content-length: 4 
test 


可 以 看 出 ，HITP 头 部 也 属于 可 变 长 度 的 字符 串 ， 它 与 HITP 请 求 

行 和 包 体 间 都 是 通过 换行 符 来 区 分 的 。 同 时 ， 它 与 解析 HTTP 请 求 行 一 
样 ， 都 需要 使 用 状态 机 来 解析 数据 。 既 然 HTTP 请 求 行 和 头 部 都 是 变 长 
的 ， 对 它们 的 总 长 度 当 然 是 有 限制 的 。 从 图 11-3 的 第 6 步 可 以 看 出 ， 当 
最 初 分 配 的 大 小 为 dient_header_buffer_size 的 缓冲 区 且 无 法 容纳 下 完整 
的 HTTP 请 求 行 或 者 头 部 时 ， 会 再 次 分 配 大 小 为 
large_client_header_buffers (这 两 个 值 背 为 nginx.conf 文 件 中 指定 的 配置 
项 ) 的 缓冲 区 ， 同 时 会 将 原先 缓冲 区 的 内 容 复制 到 新 的 缓冲 区 中 。 所 


以 ， 这 意味 着 可 变 长 度 的 HTTP 请 求 行 加 上 HTTP 头 部 的 长 度 总 和 不 能 
超过 large_client_header_buffers 指 定 的 字 廊 数 ， 否 则 Nginx 将 会 报错 。 


先 来 看 看 图 11-4 中 展示 的 HTTP 框 架 使 用 
ngx_http_process_request_headers 方 法 接收 、 解 析 HTTP 头 部 的 流程 。 


图 11-4 中 分 支 较 多 ， 下 面 详细 地 解释 一 下 图 中 的 11 个 步骤 。 


1) 如 同 接收 http 请 求 行 一 样 ， 首 先 检 查 当 前 的 读 事 件 是 否 已 经 超 
时 。 检 查 方法 仍然 是 检查 事件 的 timeout 标 志 位 ， 如 果 为 1， 则 表示 接收 
请 求 已 经 超时 ， 这 时 调用 ngx_http_close_request 方 法 关闭 连接 ， 同 时 退 


出 ngx_http_process_request_headers 方 法 。 


2) 检查 接收 HTTP 请 求 头 部 的 header_in 缓 冲 区 是 否 用 尽 ， 当 
header in 缓冲 区 的 pos 成 员 指 向 了 end 成 员 时 ， 表 示 已 经 用 尽 ， 这 时 需要 
调用 ngx_http_alloc_large_header_ buffer 方 法 分 配 更 大 、 更 多 的 缓冲 区 ， 
如 同 图 11-3 中 的 第 6 步 。 如 果 缓 冲 区 还 没有 用 尽 ， 则 跳 到 第 4 步 中 执行 。 


3) 事实 上 ，ngx_http_alloc_large_header_buffer 方 法 会 有 3 种 返回 
值 ， 其 中 NGX_OK 表 示 成 功 分 配 到 更 大 的 缓冲 区 ， 可 以 继续 接收 客户 
端 发 来 的 字符 流 ，NGX_DECLINED 表 示 已 经 达到 缓冲 区 大 小 的 上 限 ， 
无 法 分 配 更 大 的 缓冲 区 ;NGX_ERROR 表 示 出 现 错误 。 所 以 ， 当 返回 
NGX_ERROR 时 ， 跳 转 到 第 1 步 执行 ， 而 当 返 回 NGX_DECLINED 时 ， 
需要 向 用 户 返 回 错误 并 且 同 时 退出 ngx_http_process_request_headers 方 


法 ， 错 误 码 由 安 NGX_HTTP REQUEST _HEADER_TOO LARGE 表 
示 ， 也 束 是 494， 实 际 上 这 一 过 程 是 通过 调用 ngx_http_finalize_request 
方法 来 实现 的 《参见 11.10.6 节 ) ; 如 果 返 回 NGX_OK， 则 继续 第 4 步 执 


一 


休 。 


[检查 是 否 接收 请 求 超时 ] 
[没有 超时 ] 


[header in 缓冲 区 已 经 用 尽 ] 


2) 分 配 更 大 
缓冲 区 


[已 达到 最 大 绥 存 限制 ] es 


[已 经 超时 ] 
[header_in 还 有 空闲 内 存 接收 字符 流 ] 


[分 配 绥 存 错误 ] 


分 配 到 更 大 的 缓 有 | 


3) 癌 客户 ? 
494 响 应 并 结 ; 


全 


[需要 继续 接收 才能 解析 ] 
[连接 错误 或 用 户 关闭 连接 ] 


[需要 继续 接收 数据 ] 
XX 


[接收 到 新 数据 ] 5 将 读 事 全 深 加 到 
定时 器 与 epoll 中 


[检查 recv 方 法 返回 值 ] 


6) Re 


pA 


[检查 状态 机 到 回 值 7 设 硬 解 入 
的 头 部 


行 HTTP 头 部 ] 


[解析 失败 ] 


9) 根 | ihost 头 部 找到 
对 应 的 server 1) 调 用 ngx_http_close_request 
关闭 请 求 


10) 检查 部 分 头 音 
信息 是 否 合法 


11) 调 用 ngx_http_process_request 
方法 处 理 请 求 


名 
图 11-4 ”ngx_http_process_request_headers 方 法 接收 HTTP 头 部 的 流程 图 


4) 接收 客户 端 发 来 的 字符 流 ， 即 把 内 核 套 接 字 缓冲 区 上 的 字符 流 
接收 到 header_in 绥 冲 区 中 。 这 一 过 程 是 通过 调用 封 泪 过 的 recv 方 法 实现 
的 ， 如 有 果 过 程 中 出 现 错误 ， 仍 然 跳 转 到 第 1 步 执行 ， 如 果 没 有 接收 到 数 
据 ， 但 错误 码 表 明 仍 然 需 要 再 次 接收 数据 ， 则 跳 转 到 第 5 步 执行 ， 如 采 
成 功 接收 到 数据 ， 则 跳 转 到 第 6 步 执行 。 


5) 这 个 步骤 将 该 读 事 件 添 加 到 epol 和 定时 器 中 ， 实 际 上 就 是 图 11- 
3 中 第 3 步 和 第 4 步 的 合并 ， 不 再 痪 述 。 


6) 调用 ngx_http_parse_header line 方 法 解析 缓冲 区 中 的 字符 流 。 这 
种 方法 有 3 个 返回 值 : 返回 NGX_OK 时 ， 表 示 解 析出 一 行 HTTP 头 部 ， 
这 时 需要 跳 转 到 第 7 步 设置 这 行 已 经 解析 出 的 HITTP 头 部 ;返回 
NGX_HTTP_PARSE_HEADER_DONE 时 ， 表 示 已 经 解析 出 了 完整 的 
HTTP 头 部 ， 这 时 可 以 准备 开始 处 理 HTTP 请 求 了 〈11.6 节 介绍 ) ; 返回 
NGX_AGAIN 时 ， 表 示 还 需要 接收 到 更 多 的 字符 流 才能 继续 解 机 ， 这 
时 需要 跳 转 到 第 2 步 去 接收 更 多 的 字符 流 ， 除 此 之 外 的 错误 情况 ， 将 跳 
转 到 第 8 步 发 送 400 错 误 给 客户 端 。 


7) 将 解析 出 的 HTTP 头 部 设置 到 表示 ngx_http_request_t 结 构 体 
headers_in 成 员 的 headers 链 表 中 。 从 3.6.3 广 中 可 以 看 出 ， 开 发 HTTP 模 块 
时 获取 到 的 HITP 头 部 就 是 在 这 个 步骤 中 设置 的 。 


8) 当 调 用 ngx_http_parse_header_line 方 法 解析 字符 串 构 成 的 HTTP 
时 ， 是 有 可 能 遇 到 非法 的 或 者 Nginx 当 前 版 本 不 支持 的 HTTP 头 部 的 ， 
这 时 该 方法 会 返回 错误 ， 于 是 调用 ngx_http_finalize_request 方 法 ， 回 容 
户 端 发 送 NGX_HTTP_BAD_REQUEST 宏 对 应 的 400 错 误 码 响应 。 


9) 当 ngx_http_parse_header_line 方 法 认为 已 经 解析 到 完整 的 HTTP 
头 部 时 ， 将 会 根据 HTTP 头 部 中 的 host 字 段 情 况 ， 调 用 
ngx_http_find_virtual_server 方 法 找到 对 应 的 虚拟 主机 配置 块 ， 也 就 是 第 
10 章 中 介绍 过 的 ngx_http_core_srv_conf t 结 构 体 。 这 一 步 会 导致 图 11-2 
的 第 4 步 中 ngx_http_request_t 结 构 体 里 的 srv_conf、loc_conf 成 员 被 重新 
设置 ， 以 指向 正确 的 虚拟 主机 。 


10) 这 一 步骤 将 检查 以 上 步骤 中 接收 解析 出 的 HITP 头 部 是 否 合 
法 ， 主 要 包括 以 下 几 项 : 如 果 HTTP 版 本 为 1.1， 则 host 头 部 不 可 以 为 
x， 和 否则 返回 400 Bad Request 错 误 啊 应 给 客户 端 ; 如 果 传 递 了 Content- 
Length 头 部 ， 那 么 它 必须 是 合法 的 数字 ， 否 则 会 返回 400 Length 
Required 错 误 啊 应 给 客户 端 ， 如 采 请 求 使 用 了 PUT 方法 ， 那 么 必须 传递 
Content-Length 头 部 ， 否 则 会 返回 400 Length Required 错 误 啊 应 给 客户 


人 


de 
全 


端 。 


11) 调用 ngx_http_process_request 方 法 开始 使 用 各 HTTP 模 块 正式 
地 在 业务 上 处 理 HTTP 请 求 。 


以 上 11 步 骤 仅 专注 于 接收 并 解析 出 全 部 的 HITP 头 部 ， 同 时 检查 它 
们 的 合法 性 ， 并 将 解析 出 的 HITP 头 部 设置 到 ngx_http_request_t 结 构 体 
里 的 合适 位 置 。 接 下 来 开始 讨论 如 何 使 用 以 上 两 节 中 已 经 解析 好 的 
HTTP 请 求 行 和 头 部 。 


11.6 “处理 HTTP 请 求 


在 接收 到 完整 的 HTTP 头 部 后 ， 已 经 拥有 足够 的 必要 信息 开始 在 业 
务 上 处 理 HITP 请 求 了 。 本 万 将 说 明 HITTP 框 淋 是 如 何 台 集 负责 具 体 功 
能 的 各 HTTP 模 块 合作 处 理 请 求 的 。 在 图 11-4 的 第 11 步 及 图 11-3 的 第 10 
步 中 ， 最 后 都 是 通过 调用 ngx_http_process_request 方 法 开始 处 理 请 求 ， 
本 节 将 讨论 ngx_http_process_request 方 法 的 流程 ， 而 且 
ngx_http_process_request 方 法 只 是 处 理 请 求 的 开始 ， 对 于 基于 事件 驱动 
的 异步 HTTP 框 架 来 说 ， 处 理 请 求 并 不 是 一 步 可 以 完成 的 ， 所 以 我 们 也 
会 讨论 后 续 TCP 连 接 上 的 回调 方法 ngx_http_request_handler 的 流程 。 首 
先 来 看 看 接收 完 HITTP 头 部 后 ngx_http_process_request 方 法 所 做 的 事 
情 ， 如 图 11-5 所 示 。 


[检查 TCP a 


[ 读 事件 在 定时 器 中 ] [ 读 事件 没有 在 定时 器 中 ] 


1) 把 读 事件 从 
定时 器 中 移 除 


2) 重新 设置 连接 上 
读 / 写 事件 的 处 理 方法 


3 ) 设置 请 求 的 
read_event_handler 方 法 
[检查 请 求 的 internal 标志 位 ] 


[internal 为 1] 4) 设置 phase_handler 序号 为 


server_rewrite_index 


[internal 为 0] 


5 ) 设 置 请 求 的 
phase_handler 序 号 为 0 


6 ) 设置 请 求 的 write_event_handler 


调 方 法 


7) 调用 ngx_http_core_run_phases 
方法 集成 HTTP 模 块 处 理 请 求 


8 ) 调 用 ngx_http_run_posted_requests 
方法 执行 post 请 求 


图 11-5 ”ngx_http_process_request 处 理 HTTP 请 求 的 流程 图 


下 面 详细 介绍 图 11-5 中 的 8 个 步 又。 


1) 由 于 现在 已 经 开始 准备 调用 各 HTTP 模 块 处 理 请 求 了 ， 因 此 不 
再 存在 接收 HTTP 请 求 头 部 超时 的 问题 ， 那 就 需要 从 定时 器 中 把 当前 连 
接 的 谈 事 件 移 除 了 。 检 查 读 事件 对 应 的 timer_set 标 志 位 ， 为 1 时 表示 读 
事件 已 经 添加 到 定时 器 中 了 ， 这 时 需要 调用 ngx_del_timer 从 定时 器 中 移 
除 读 事件 ， 如 果 timer_set 标 志 位 为 0， 则 直接 执行 第 2 步 。 


2) 从 现在 开始 不 会 再 需要 接收 HITP 请 求 行 或 者 头 部 ， 所 以 需要 
重新 设置 当前 连接 读 / 写 事件 的 回调 方法 。 在 这 一 步骤 中 ， 将 同时 把 读 
事件 、 写 事件 的 回调 方法 都 设置 为 ngx_http_request_handler 方 法 ， 在 下 
面 的 图 11-7 中 会 介绍 到 这 个 方法 ， 请 求 的 后 续 处 理 都 是 通过 
ngx_http_request_handler 方 法 进行 的 。 


3) 设置 ngx_http_request_t 结 构 体 的 read_event_handler 方 法 为 
ngx_http_block_reading。 前 面 11.3 节 中 曾 介绍 过 read_event_handler 方 
法 ， 当 再 次 有 读 事件 到 来 时 ， 将 会 调用 read_event_handler 方 法 处 理 请 
求 。 而 这 里 将 它 设置 为 ngx_http_block_reading 方 法 ， 这 个 方法 可 认为 不 
做 任何 事 ， 它 的 意义 在 于 ， 目 前 已 经 开始 处 理 HTTP 请 求 ， 除 非 某 个 
HTTP 模 块 重新 设置 了 read_event_handler 方 法 ， 否 则 任何 读 事 件 都 将 得 
不 到 处 理 ， 也 可 以 认为 读 事件 被 阻 蹇 了。 


4) 检查 ngx_http_request_t 结 构 体 的 internal 标 志 位 ， 如 果 internal 为 
0， 则 继续 执行 第 5 步 ， 如 果 internal 标 志 位 为 1， 则 表示 请 求 当 前 需要 做 
内 部 跳 转 ， 将 要 把 结构 体 中 的 phase_handler 序 号 置 为 
server_rewrite_index。 先 来 回顾 一 下 10.6.1 市 ， 注 意 
ngx_http_phase_engine_t 结 构 体 中 的 handlers 动 态 数 组 中 保存 了 请 求 需 要 
经 历 的 所 有 回调 方法 ， 而 server_rewrite_index 则 是 handlers 数 组 中 
NGX_HTTP_SERVER_REWRITE_PHASE 人 处 理 阶 段 的 第 一 个 
ngx_http_phase_handler_t 回 调 方 法 所 处 的 位 置 。 


究竟 handlers 数 组 是 怎么 使 用 的 呢 ? 事实 上 ， 它 要 配合 着 
ngx_http_request_t 结 构 体 的 phase_handler 序 号 使 用 ， 由 phase_handler 指 
定 着 请 求 将 要 执行 的 handlers 数 组 中 的 方法 位 置 。 注 意 ，handlers 数 组 中 
的 方法 都 是 由 各 个 HTTP 模块 实现 的 ， 这 束 是 所 有 HTTP 模 块 能 够 共同 
处 理 请 求 的 原因 。 


在 这 一 步骤 中 ， 把 phase_handler 序 号 设 为 server_rewrite_index， 这 
意味 着 无 论 之 前 执行 到 哪 一 个 阶段 ， 马 上 都 要 重新 从 
NGX_HTTP_SERVER_REWRITE_PHASE 阶 段 开始 再 次 执行 ， 这 是 
Nginx 的 请 求 可 以 反复 rewrite 重 定 同 的 基础 。 


5) 当 internal 标 志 位 为 0 时 ， 表 示 不 需要 重 定向 (如 刚 开 始 处 理 请 
求 时 ) ， 将 phase_handler 序 号 置 为 0， 意 味 着 从 ngx_http_phase_engine t 
指定 数组 的 第 一 个 回调 方法 开始 执行 (参见 10.6 访 ， 了 和解 


ngx_http_phase_engine_t 是 如 何 将 各 HTTP 模 块 的 回调 方法 构造 成 
handlers 数 组 的 ) 。 


6) 设置 ngx_http_request_t 结 构 体 的 write_event_handler 成 员 为 
ngx_http_core_run_phases 方 法 。 如 同 read_event_handler 方 法 一 样 ， 在 图 
11-7 中 可 以 看 到 write_event_handler 方 法 是 如 何 被 调用 的 。 


7) 执行 hgx_http_core_run_phases 方 法 ， 其 流程 如 图 11-6 所 示 。 


8) 调用 ngx_http_run_posted_requests 方 法 执行 post 请 求 ， 参 见 11.7 


节 。 


上 述 第 7 步调 用 了 ngx_http_core_run_phases 方 法 ， 该 方法 将 开始 调 
用 各 个 HITP 模 块 共同 处 理 请 求 。 在 第 10 章 我 们 讨论 过 HTTP 框 架 的 初 
始 化 ， 在 这 一 过 程 中 是 允许 各 个 HTTP 模块 将 自己 的 处 理 方法 按照 11 个 
ngx_http_phases 阶 段 添加 到 全 局 的 ngx_http_core_main_conf t 结 构 体 中 
的 。 下 面 简单 地 回顾 一 下 它 的 定义 ， 如 下 所 示 。 


typedef struct { 


//_ HTTP 框架 初 始 化 后 各 个 


HTTP 模 块 构造 的 处 理 方法 将 组 成 


phase_engine 

ngx_http_phase_engine_t phase_engine; 
} ngx_http_core_main_conf_t; 
typedef struct { 

/A* 


ngx_http_phase_handler_t 结 构 体 构成 的 数组 ， 每 一 个 数组 成 员 代 表 


xi 
Ly 
| 
全 


HTTP 模 块 所 添加 的 一 个 处 理 方法 


4 
ngx_http_phase_ handler_t *handlers; 


} ngx_http_phase_engine_t; 
typedef struct ngx_http_phase handler_s ngx_http_phase_handler_t; 
struct ngx_http_phase_ handler_s { 

/每 个 


handler 方 法 必须 对 应 着 一 个 
checker 方 法 ， 这 个 


checker 方 法 由 


HTTP 框 架 实现 


* 

/ 
ngx_http_phase_ handler_pt checker; 
// 各 个 

HTTP 模 块 实现 的 方法 


ngx_http_handler_pt handler,; 


}; 


可 以 看 到 ， 根 据 ngx_http_core_main_conf t 结 构 体 的 phase_engine 成 
员 即 可 依次 调用 各 个 HTTP 模块 来 共同 处 理 一 个 请 求 。 下 面 看 看 图 11-6 
中 展示 的 ngx_http_core_run_phases 方 法 的 流程 。 


是 否 实现 checker 方 法 ] 


[实现 Jchecker 方 法 | 


执 Jphase_handler 序号 指定 的 [返回 非 NGX_OK] 
checker 方 法 


[未 实现 checker 方 法 ] [检查 check 方 法 返回 值 ] 


| checker 方 法 返回 NGX_OK| 


图 11-6 ”ngx_http_core_run_phases 方 法 的 执行 流程 


在 图 11-6 中 仅 会 执行 每 个 ngx_http_phase_handler t 处 理 阶 段 的 
checker 方 法 ， 而 不 会 执行 handler 方 法 ， 其 原因 已 在 10.6 方 讲 过 ， 这 是 因 
为 handler 方 法 其 实 仅 能 在 checker 方 法 中 被 调用 ， 而 且 checker 方 法 由 
HTTP 框 架 实 现 ， 所 以 可 以 控制 各 HTTP 模 块 实现 的 处 理 方法 在 不 同 的 
阶段 中 采用 不 同 的 调用 行为 。 再 来 简单 地 看 一 下 调用 的 源 代 码 。 


void ngx_http_core_run_phases(ngx_http_redquest t *r) 


ngx_int_t rc' 

ngx_http_phase_handler_t *ph; 

ngx_http_core _ main conf_t *cmcf， 

cmcf = ngx_http_get module main conf(r, ngx_http_core module); 
ph = cmcf->phase_engine.handlers; 

while (ph[r->phase_handler].checker) { 


rc = ph[r->phase_handler].checker(r, &ph[r->phase_handler]); 


if (rc == NGX_OK) { 
return; 
} 
} 
} 


可 以 看 到 ，ngx_http_request_t 结 构 体 中 的 phase_handler 成 员 将 决定 
执行 到 哪 一 阶段 ， 以 及 下 一 阶段 应 当 执行 哪个 HTTP 模 块 实现 的 内 容 。 
在 图 11-5 的 第 4 步 和 第 5 步 中 可 以 看 到 请 求 的 phase_handler 成 员 会 被 重 
置 ， 而 HTTP 框架 实现 的 checker 方 法 也 会 修改 phase_handler 成 员 的 值 。 
表 11-1 列 出 了 HTTP 框 架 实 现 的 所 有 checker 方 法 ， 如 下 所 示 。 


表 11-1 HTTP 框 架 为 11 个 阶段 实现 的 checker 方 法 


阶段 名 称 checker 方法 
NGX HTTP POST READ PHASE ngx http core generic phase 
NGX HTTP SERVER REWRITE PHASE ngx http_core rewrite phase 
NGX HTTP FIND CONFIG PHASE ngx http_core find config phase 


NGX HTTP REWRITE PHASE ngx http_core rewrite phase 
NGX HTTP POST REWRITE PHASE 


ngx http_core_ post rewrite phase 


NGX HTTP PREACCESS PHASE 
NGX HTTP ACCESS PHASE 


NGX HTTP POST ACCESS PHASE 


NGX HTTP TRY FILES PHASE 
NGX HTTP CONTENT PHASE 
NGX_HTTP LOG PHASE 


ngx_ http_core generic phase 


ngx http_core access phase 


ngx http_core post access phase 


ngx http_core try_files phase 


ngx_ http_core_content phase 


ngx http_core generic phase 


我 们 在 10.6 节 中 曾经 详细 介绍 过 HTTP 阶 段 。 在 11 个 阶段 中 其 中 7 个 


是 允许 各 个 HTTP 模 块 向 阶段 中 任 


添加 自己 实现 的 handler 处 理 方法 


的 ， 但 同一 个 阶段 中 的 所 有 handler 处 理 方法 都 拥有 相同 的 checker 方 
法 ， 见 表 11-1。 我 们 知道 ， 每 个 阶段 中 处 理 方法 的 返回 值 都 会 以 不 同 的 
方式 影响 HTTP 框 架 的 行为 ， 而 在 图 11-6 中 也 可 以 看 到 ，checker 方 法 在 


返回 NGX_OK 和 其 他 值 时 也 会 导致 不 同 的 结果 (每 个 checker 方 法 的 返 
回 值 实际 上 与 handler 处 理 方法 的 返回 是 相关 的 ， 参 见 10.6.2 节 ~10.6.12 
节 中 对 各 个 阶段 的 说 明 ) 。 当 checker 方 法 的 返回 值 非 NGX_OK 时 ， 意 
味 着 向 下 执行 phase_engine 中 的 各 处 理 方法 ;反之 ， 当 任何 一 个 checker 
方法 返回 NGX_OK 时 ， 意 味 着 把 控制 权 交 还 给 Nginx 的 事件 模块 ， 由 它 
根据 事件 (网 络 事 件 、 定 时 器 事件 、 异 步 WO 事 件 等 再 次 调度 请 求 。 
然而 ， 一 个 请 求 多 半 需 要 Nginx 事 件 模 块 多 次 地 调度 HTTP 模 块 处 理 ， 
这 时 就 要 看 在 图 11-5 中 第 2 步 设置 的 读 / 写 事件 的 回调 方法 
ngx_http_request_handler 的 功能 了 ， 如 图 11-7 所 示 。 


1) 由 触发 事件 中 取出 


ngx_http _Trequest t 结构 体 
[检查 当前 事件 是 可 读 事 件 还 是 可 写 事件 ] 


[ 当前 事件 可 读 ] [当前 事件 可 写 ] 


2 ) 执行 write_event_ handler 方 法 


3) 执行 read_event_handle! 方 法 


4 ) 调用 ngx http_run_posted_requests 方 法 执行 post 请 求 


图 11-7 ngx_http_request_handler 方 法 的 执行 流程 


通常 来 说 ， 在 接收 完 FETTP 头 部 后 ， 是 无 法 在 一 次 Nginx 框 架 的 调 
度 中 人 处 理 完 一 个 请 求 的 。 在 第 一 次 接收 完 HTTP 尖 部 后 ，HTTP 框 架 将 
调度 ngx_http_process_request 方 法 开始 处 理 请 求 ， 这 时 根据 图 11-6 中 的 
流程 可 以 看 到 ， 如 果 某 个 checker 方 法 返回 了 NGX_OK， 则 将 会 把 控制 
权 交 还 给 Nginx 框 架 。 当 这 个 请 求 上 对 应 的 事件 再 次 触发 时 ，HTTP 框 
架 将 不 会 再 调度 ngxX_http_process_request 方 法 处 理 请 求 ， 而 是 由 
ngx_http_request_handler 方 法 开始 处 理 请 求 。 下 面 来 看 看 图 11-7 中 列 出 
的 ngx_http_request_handler 方 法 的 流程 : 


1) ngx_http_request_handler 是 HTTP 请 求 上 读 / 写 事件 的 回调 方法 。 
在 ngx_event_t 结 构 体 表示 的 事件 中 ，data 成 员 指 向 了 这 个 事件 对 应 的 
ngX_connection_t 和 连接， 而 根据 11.3 节 中 的 内 容 可 以 看 到 ， 在 HITP 框 态 
的 ngx_connection_t 结 构 体 中 的 data 成 员 则 指 癌 了 ngx_http_request_ t 结 构 
体 。 至 无 疑问 ， 只 有 拥有 了 ngx_http_request_t 结 构 体 才 可 以 处 理 HTTP 
请 求 ， 而 第 一 个 步骤 是 从 事件 中 取出 ngx_http_request_t 结 构 体 。 


2) 检查 这 个 事件 的 write 可 写 标志 ， 如 果 write 标 志 为 1， 则 调用 
ngx_http_request_t 结 构 体 中 的 write_event_handler 方 法 。 注 意 ， 我 们 在 
ngx_http_handler 方 法 中 ( 即 图 11-5 的 第 6 步 ) 已 经 将 write_event_handler 
设置 为 ngx_http_core_run_phases 方 法 ， 而 一 般 我 们 开发 的 不 太 复 杂 的 
HTTP 模 块 是 不 会 重新 设置 write_event_handler 方 法 的 ， 因 此 ， 一 旦 有 可 


写 事件 时 ， 就 会 继续 按照 图 11-6 的 流程 执行 hgx_http_core_run_phases 方 
法 ， 并 继续 按 阶段 调用 各 个 HTTP 模 块 实现 的 方法 处 理 请 求 。 


3) 调用 ngx_http_request_t 结 构 体 中 的 read_event_handler 方 法 。 注 
意 比 较 第 2 步 和 第 3 步 ， 如 果 一 个 事件 的 读 写 标志 同时 为 1 时， 仅 
write_event_handler 方 法 会 被 调用 ， 即 可 写 事 件 的 处 理 优先 于 可 读 事件 
(这 正 是 Nginx 高 性 能 设计 的 体现 ， 优 先 处 理 可 写 事 件 可 以 尽快 释放 内 
存 ， 尽 量 保持 各 HITP 模 块 少 使 用 内 存 以 提高 并 发 能 力 ) 。 


4) 调用 ngx_http_run_posted_requests 方 法 执行 post 请 求 ， 参 见 11.7 


二 


以 上 重点 讨论 了 ngx_http_process_request 和 ngx_http_request_handler 
这 两 个 方法 ， 其 中 ngx_http_process_request 方 法 负责 在 接收 完 HITTP 头 
部 后 ， 第 一 次 与 各 个 HITP 模 块 共同 按 阶段 处 理 请 求 ， 而 对 于 
ngx_http_request_handler 方 法 ， 如 果 ngx_http_process_request 没 能 处 理 完 
请 求 ， 这 个 请 求 上 的 事件 再 次 被 触发 ， 那 就 将 由 此 方法 继续 处 理 了 。 


这 两 个 方法 的 共通 之 处 在 于 ， 它 们 都 会 先 按 阶段 调用 各 个 HTTP 模 
块 处 理 请 求 ， 再 处 理 post 请 求 。 关 于 post 请 求 的 内 容 下 文 会 介绍 ， 而 按 
阶段 处 理 请 求实 际 上 就 是 图 11-6 中 摘 述 的 流程 ， 也 就 是 通过 每 个 阶段 的 
checker 方 法 来 实现 。 在 表 11-1 中 可 以 看 到 ， 在 各 个 HITP 模 块 能 够 介入 
的 7 个 阶段 中 ， 实 际 上 共享 了 4 个 checker 方 法 : 


ngX_http_cCore_generic_phase、ngx_http_core_Tewrite_phase、 
ngx_http_core_access_phase、 ngx_http_core_content_phase ， 在 10.6 广 中 


我 们 曾经 简单 地 介绍 过 它们 。 


这 4 个 checker 方 法 的 主要 任务 在 于 ， 根 据 phase_handler 执 行 某 个 
HTTP 模 块 实现 的 回调 方法 ， 并 根据 方法 的 返回 值 决定 :当前 阶段 已 经 
完全 结束 了 吗 ? 下 次 要 执行 的 回调 方法 是 哪 一 个 ?究竟 是 立刻 执行 下 
一 个 回调 方法 还 是 先 把 控制 权 交还 给 epoll? 下 面 通过 介绍 这 4 个 checker 
方法 来 回答 上 述 3 个 问题 (其 他 checker 方 法 仅 由 HTTP 框 架 使 用 ， 这 里 
不 再 详细 介绍 ) 。 


11.6.1 ngx_http_core_ generic phase 


从 表 11-1 中 可 以 看 出 ， 有 3 个 HTTP 阶 段 都 使 用 了 
ngx_http_core_generic_phase 作 为 它们 的 checker 方 法 ， 这 意味 着 任何 试 
图 在 NGX_HTTP_POST_READ _PHASE、 
NGX_HTTP_PREACCESS_PHASE、NGX_HTTP_LOG _PHASE 这 3 个 阶 
段 处 理 请 求 的 HTTP 模 块 都 需要 了 解 ngx_http_core_generic_phase 方 法 到 
底 做 了 些 什么 。 图 11-8 中 描述 了 ngx_http_core_generic_phase 方 法 的 流 
程 ， 可 以 看 到 ， 在 调用 了 当前 阶段 的 hnandler 方 法 后 ， 根 据 返 回 值 的 不 
同 可 能 导致 4 种 不 同 的 结果 。 


下 面 说 明 图 11-8 中 所 列 的 5 个 步骤 。 


1) 首先 调用 HTTP 模 块 实现 的 handler 方 法 ， 这 个 方法 的 实现 当然 
是 不 允许 有 阻塞 操作 的 ， 它 会 立刻 返回 。 根 据 它 的 返回 值 类 型 ， 将 会 
有 4 种 不 同 的 结果 : 返回 NGX_OK 时 直接 跳 转 到 第 2 步 执行 ， 返回 
NGX_DECLINED 时 跳 转 到 第 3 步 执 行 ， 返回 NGX_AGAIN 或 者 
NGX_DONE 时 跳 转 到 第 4 步 执行 ;返回 其 他 值 时 跳 转 到 第 5 步 执 行 。 


2) 如 果 HTTP 模 块 实现 的 handler 方 法 返回 NGX_OK， 这 意味 着 当 
前 阶段 已 经 执行 完毕 ， 需 要 跳 转 到 下 一 个 阶段 执行 。 例 如 ， 在 
NGX_HTTP_ACCESS_PHASE 阶 段 中 可 能 有 两 个 HITP 模 块 都 注册 了 回 
调 方 法 ， 在 执行 第 1 个 HTTP 模 块 的 回调 方法 时 ， 如 果 它 返回 了 
NGX_OK， 那 么 就 不 再 执行 第 2 个 HTTP 模 块 实现 的 回调 方法 了 ， 而 是 
跳 转 到 下 一 个 阶段 “如 NGX_HTTP POST _ ACCESS_PHASE) 开始 执 
行 。 注 意 ， 此 时 ngx_http_core_generic_phase 方 法 会 返回 NGX_AGAIN， 
从 图 11-6 中 可 以 看 到 ， 非 NGX_OK 的 返回 值 不 会 使 HTTP 框 架 把 进程 控 
制 权 交还 给 epoll 等 事件 模块 ， 而 是 会 继续 立刻 执行 请 求 的 后 续 处 理 方 


法 。 


1 ) 调 用 HTTP 模 块 实现 的 


handler 方 法 处 理 请 求 


[检查 handle 访 法 的 返回 值 ] 


2 将 phase_handler 设 为 [ 返 回 NCX_DECLINED] 


next 并 返回 NGX_AGAIN 


[返回 NGX_AGAIN 或 者 NGX_DONE] 


[返回 其 他 值 ] 3) phase_handler++ 


并 返回 NGX_AGAIN 


4) 直接 返回 NGX_OR 


5 ) 调用 ngx_ http_finalize _request 


结束 请 求 并 返回 NGX_OK 
图 11-8 ngx_http_core_generic_phase 方 法 的 执行 流程 


3) 如 果 handler 方 法 返回 NGX_DECLINED， 则 会 执行 下 一 个 回调 
方法 。 继 续 第 2 步 中 的 例子 ， 在 NGX_HTTP_ACCESS_PHASE 阶 段 ， 第 


1 个 HTTP 模块 的 回调 方法 返回 NGX_DECLINED 后 ， 下 一 个 将 要 执行 的 
方法 仍然 属于 NGX_HTTP_ACCESS_PHASE 阶 段 ， 即 第 2 个 HTTP 模 块 
实现 的 回调 方法 。 注 意 ， 这 时 ngx_http_core_generic_phase 返 回 的 仍然 
是 NGX_AGAIN， 它 意味 着 HTTP 框 架 会 紧 接 着 继续 执行 请 求 的 后 续 处 
理 方 潜 。 


4) 如 果 handler 方 法 返回 NGX_AGAIN 或 者 NGX_DONE， 则 意味 着 
刚才 的 handler 方 法 无 法 在 这 一 次 调度 中 处 理 完 这 一 个 阶段 ， 它 需要 多 
次 调度 才能 完成 ， 也 就 是 说 ， 刚 刚 执行 过 的 handler 方 法 希望 : 如 果 请 
求 对 应 的 事件 再 次 被 触发 和 时， 将 由 ngx_http_request_handler 通 过 
ngx_http_core_run_phases 再 次 调用 这 个 handler 方 法 。 直 接 返 回 NGX_OK 
会 使 得 HTTP 框 染 立 刻 把 控制 权 交 还 给 epoll 事 件 框 架 ， 不 再 处 理 当 前 请 
求 ， 唯 有 这 个 请 求 上 的 事件 再 次 被 触发 才 会 继续 执行 。 


1 ) 调用 HTTP 模 块 实 现 的 


handler 处 理 方 法 
[检查 handle 方 法 的 返回 值 ] 


返回 NGCX_DECLINED] 


下 DONE] 2) phase_ handler+ 莽 返 
NGX_AGAIN 
[ 返 si 
3 ) 直接 返回 
NGX_OK 


4) 六 用 ngx_ i finalize _request 


结束 请 求 并 返回 NGX_OK 


© 


图 11-9 ngx_http_core_rewrite_phase 方 法 的 执行 流程 


5) 如 果 handler 方 法 返回 了 第 2、 第 3、 第 4 步 中 以 外 的 返回 值 ， 则 
调用 ngx_http_finalize_request 结 束 请 求 。ngx_http_finalize_request 方 法 中 
的 参数 就 古 handler 方 法 的 返回 值 ， 其 影响 参见 11.10.6 订 。 


当 我 们 开发 的 HTTP 模 块 试图 介入 
NGX_HTIP_ POST_READ PHASE、 
NGX_HTTP PREACCESS_ PHASE、NGX_HTTP LOG_PHASE 这 3 个 阶 
段 处 理 请 求 时 ， 实 现 的 handler 方 法 需要 根据 上 述 步 又 决定 返回 值 。 
ngx_http_core_generic_phase 可 以 帮助 我 们 较为 简单 地 实现 强大 的 异步 
无 阻塞 处 理 能 


11.6.2 ngx_http_core_rewrite_phase 


ngx_http_core_rewrite_phase 方 法 充当 了 用 于 重 写 URL 的 
NGX_HTTP SERVER_REWRITE_ PHASE 和 
NGX_HTTP_REWRITE_PHASE 这 两 个 阶段 的 checker 方 法 。 图 11-9 中 描 
述 了 ngx_http_core_rewrite_phase 方 法 的 流程 ， 可 以 看 到 ， 在 调用 了 当前 
阶段 的 handler 方 法 后 ， 根 据 返 回 值 的 不 同 可 能 会 寻 人 致 3 种 结果 。 


下 面 简要 描述 一 下 图 11-9 中 所 列 的 4 个 步 又 。 


1) 首先 调用 HTTP 模 块 实现 的 handler 方 法 ， 根 据 它 的 返回 值 类 
型 ， 将 会 有 3 种 不 同 的 结果 : 返回 NGX_DECLINED 时 跳 转 到 第 2 步 执 


行 ; 返回 NGX_DONE 时 跳 转 到 第 3 步 执行 ， 返回 其 他 值 时 跳 转 到 第 4 步 


2) 如 果 handler 方 法 返回 NGX_DECLINED， 将 phase_handler 加 1 表 
示 将 要 执行 下 一 个 回调 方法 。 注 意 ， 此 时 返回 的 是 NGX_AGAIN， 
HTTP 框 架 不 会 把 进程 控制 权 交 还 给 epoll 事 件 框架 ， 而 是 继续 立刻 执行 
请 求 的 下 一 个 回调 方法 。 


3) 如 果 handler 方 法 返回 NGX_DONE， 则 意味 着 刚才 的 handler 方 
法 无 法 在 这 一 次 调度 中 处 理 完 这 一 个 阶段 ， 它 需要 多 次 的 调度 才能 完 
成 。 注 意 ， 此 时 返回 NGX_OK， 它 会 使 得 HTTP 框 架 立刻 把 控制 权 交 还 
给 epoll 等 事件 模块 ， 不 再 处 理 当 前 请 求 ， 唯 有 这 个 请 求 上 的 事件 再 次 
被 触发 时 才 会 继续 执行 。 


4) 如 果 handler 方 法 返回 除去 NGX_DECLINED 或 者 NGX_DONE 以 
处 的 其 他 值 ， 则 调用 ngx_http_finalize_request 结 束 请 求 ， 其 参数 为 
handler 方 法 的 返回 值 。 


可 以 注意 到 ，ngx_http_core_rewrite_phase 方 法 与 
ngx_http_core_generic_phase 方 法 有 一 个 显著 的 不 同 点 : 前 者 永远 不 会 
导致 跨 过 同一 个 HTTP 阶 段 的 其 他 处 理 方法 ， 就 直接 跳 到 下 一 个 阶段 来 
处 理 请 求 。 原 因 其 实 很 简单 ， 可 能 有 许多 HTTP 模块 在 
NGX_HTTP SERVER_REWRITE_ PHASE 和 


NGX_HTTP_REWRITE_PHASE 阶 段 同时 人 处理 重 写 URL 这 样 的 业务 ， 
HTTP 框 架 认为 这 两 个 阶段 的 HTTP 模 块 是 完全 平等 的 ， 序 号 靠 前 的 
HTTP 模 块 优先 级 并 不 会 更 高 ， 它 不 能 决定 序号 人 靠 后 的 HTTP 模 块 是 否 
可 以 再 次 重 写 URL。 因 此 ，ngx_http_core_rewrite_phase 方 法 绝对 不 会 把 
phase_handler 直 接 设置 到 下 一 个 阶段 处 理 方法 的 流程 中 ， 即 不 可 能 存在 
类 似 下 面 的 代码 。 


ngx_int_t ngx_http_core_rewrite phase(ngx_http_request _t *r, 
ngx_http_phase_handler_t *ph) 
{ 


r->phase_handler = ph->next; 


11.6.3 ngx_http_core_access_phase 


ngx_http_core_access_phase 方 法 是 仅 用 于 
NGX_HTTP_ACCESS_PHASE 阶 段 的 处 理 方法 ， 这 一 阶段 用 于 控制 用 
户 发 起 的 请 求 是 否 合法 ， 如 检测 客户 端的 人 P 地 址 是 否 允 许 访问 。 它 涉 
及 nginx.conf 配 置 文件 中 satisfy 配 置 项 的 参数 值 ， 见 表 11-2。 


表 11-2 相对 于 NGX_HTTP_ACCESS_PHASE 阶 段 处 理 方法 ，satisfy 配 
置 项 参数 的 意义 


satisfy 的 参数 


all 


any 


NGX_HTTP ACCESS_PHASE 阶段 可 能 有 很 多 HITP 模块 都 对 控制 请 求 的 访问 权限 感 兴趣 ， 
那么 以 哪 一 个 为 准 呢 ? 当 satisfy 的 参数 为 al 时 ， 这 些 HTTP 模块 必须 同时 发 生 作 用 ， 即 以 该 阶 
役 中 全 部 的 handler 方法 共同 决定 请 求 的 访问 权限 ， 换 句 话说， 这 一 阶段 的 所 有 handler 方法 必须 
全 部 返回 NGX_OK 才能 认为 请 求 具 有 访问 权限 

与 all 相反 ， 参 数 为 any 时 意味 着 在 NGX_HTTP_ACCESS_PHASE 阶段 只 要 有 任意 一 个 HTTP 
模块 认为 请 求 合 法 ， 就 不 用 再 调用 其 他 HTTP 模块 继续 检查 了， 可 以 认为 请 求 是 具有 访问 权限 
的 。 实 际 上 上 ， 这 时 的 情况 有 些 复 杂 : 如 果 其 中 任何 一 个 handler 方法 返回 NGX_OK， 则 认为 请 求 
具有 访问 权限 ; 如 果 某 一 个 handler 方法 返回 403 或 者 401， 则 认为 请 求 没 有 访问 权限 ， 还 需要 
检查 NGX_HTTP_ACCESS_PHASE 阶段 的 其 他 handler 方法 。 也 就 是 说 ，any 配置 项 下 任何 一 个 
handler 方法 一 旦 认为 请 求 具 有 访问 权限 ， 就 认为 这 一 阶段 执行 成 功 ， 继 续 问 下 执行 ; 如 果 其 中 一 
个 handler 方法 认为 没有 访问 权限 ， 则 未 必 以 此 为 准 ， 还 需要 检测 其 他 的 hanlder 方法 。all 和 any 
有 点 像 “&&” 和 “||” 的 关系 


对 于 表 11-2 的 any 配 置 项 ， 是 通过 ngx_http_request_t 结 构 体 中 的 
access_code 成 员 来 传递 handler 方 法 的 返回 值 的 ， 因 此 ， 


ngx_http_core_access_phase 方 法 会 比较 复杂 ， 如 图 11-10 所 示 。 


[检查 请 求 的 main 指 针 是 否 指 向 自己 ] 


<> 


[当前 请 求 就 是 原始 请 求 ] 


[当前 请 求 不 是 原始 请 求 ] 


1 ) 将 phase_handler 设 为 next 
2) 调 用 HTTP 模 块 实现 的 由. 


并 返回 NGX_AGAIN 


handler 处 理 方法 
[检查 handler 方 法 的 返回 值 ] 


<> 


[返回 其 他 值 ] 


[返回 NGX_AGAIN 或 者 NGX_DONE] 


[返回 NGX_DECLINED] 
CC 5) 取 出 当前 请 求 匹配 的 ) 


3) 直接 返回 
NGX_OK 
location 配 园 块 
[ 先 检查 location 下 satisfy 配置 项 的 值 , 再 检查 handler 方 法 的 返回 值 | 


<> 


[satisfy 配 置 为 any] 


[satisfy 配置 为 all] 
4) phase_handler ++ 
并 返回 NGX_AGAIN 


[返回 NGX_ORI 


[返回 NGX_HTTP_FORBIDDEN 或 者 > 
NGX_HTTP_UNAUTHORIZED] 


[返回 NGX_OK] 


6) 将 access_code 设 置 为 
[返回 其 他 值 ] handler 返 回 值 


[返回 非 NGX_OK 值 ] 


7) 将 access_code 


设置 为 0 


8) 调 用 ngx_http_finalize_request 
结束 请 求 并 返回 NGX_OK 


图 11-10 ”ngx_http_core_access_phase 方 法 的 执行 流程 


下 面 开 始 分 析 ngx_http_core_access_phase 方 法 的 流程 。 


1) 既然 NGX_HTTP_ACCESS_PHASE 阶 段 用 于 控制 客户 端 是 否 有 
权限 访问 服务 ， 那 么 它 就 不 需要 对 子 请 求 起 作用 。 如 何 判 断 请 求 究 竟 
是 来 自 客 户 端的 原始 请 求 还 是 被 派生 出 的 子 请 求 呢 ? 很 简单 ， 检 查 
ngx_http_request_t 结 构 体 中 的 main 指 针 即 可 。 在 11.3 节 介绍 过 的 
ngx_http_init request 方法 会 把 main 指 针 指 回 其 目 身 ， 而 由 这 个 请 求 派生 
出 的 其 他 子 请 求 中 的 main 指 针 ， 仍 然 会 指向 ngx_http_init request 方法 初 

台 化 的 原始 请 求 。 因 此 ， 检 查 main 成 员 与 ngx_http_request_t 目 身 的 指针 
是 否 相等 即 可 ， 如 下 面 的 源 代码 。 


If (r != r->main) { 
r->phase_handler = ph->next; 
return NGX_AGAIN,; 

} 


如 果 当 前 请 求 只 是 一 个 派生 出 的 子 请 求 的 话 ， 是 不 需要 执行 
NGX_HTTP_ACCESS_PHASE 阶 段 的 处 理 方 法 的 ， 那 么 直接 将 
phase_handler 设 为 下 一 个 阶段 (实际 上 是 
NGX_HTTP_POST_ACCESS_PHASE 阶 段 ) 的 处 理 方法 的 序号 。 这 时 
会 返回 NGX_AGAIN， 也 就 是 希望 HTTP 框 架 立 刻 执行 新 的 HTTP 阶 段 
的 处 理 方法 。 


2) 如 果 当 前 请 求 就 是 来 自 客户 端的 原始 请 求 ， 那 么 调用 HTTP 模 
块 在 这 一 阶段 中 实现 handler 方 法 ， 它 的 返回 值 将 会 导致 出 现 3 个 分 支 : 
返回 NGX_AGAIN 或 者 NGX_DONE 时 跳 转 到 第 3 步 执 行 ， 返 回 
NGX_DECLINED 时 跳 转 到 第 4 步 执行 ， 返 回 其 他 值 时 跳 转 到 第 5 步 继续 


回 下 执行 。 同 时 ， 在 第 5 步 之 后 ， 这 个 返回 值 由 于 nginx.conf 文 件 中 配置 
项 satisfy 的 参数 值 不 同 ， 也 将 具有 不 同 的 意义 。 


3) 返回 NGX_AGAIN 或 者 NGX_DONE 意 味 着 当前 的 
NGX_HTTP_ACCESS_PHASE 阶 段 没 有 一 次 性 执行 完毕 ， 所 以 在 这 一 
步 中 会 暂时 结束 当前 请 求 的 处 理 ， 将 控制 权 交 还 给 事件 模块 ， 
ngx_http_core_access_phase 方 法 结束 。 当 请 求 中 对 应 的 事件 再 次 触发 时 
才 会 继续 处 理 该 请 求 。 


4) 返回 NGX_DECLINED 意 味 着 handler 方 法 执行 完毕 且 “ 意 犹 未 
尽 ”， 和 希望 立刻 执行 下 一 个 handler 方 法 ， 无 论 其 是 否 属于 


NGX_HTTP ACCESS PHASE 阶段 ， 在 这 一 步 中 只 需要 把 


phase_handler 加 1， 同 时 ngx_http_core_access_phase 方 法 返回 
NGX_AGAIN 即 可 。 


5) 现在 开始 处 理 非 第 3、 第 4 步 中 返回 值 的 情况 。 由 于 
NGX_HTTP_ACCESS_PHASE 阶 段 是 在 
NGX_HTTP_FIND_CONFIG_PHASE 阶 段 之 后 的 ， 因 此 这 时 请 求 已 经 
找到 了 匹配 的 location 配 置 块 ， 移 把 location 块 对 应 的 
ngx_http_core loc_conf t 配 置 结构 体 取出 来 ， 因 为 这 里 有 一 个 配置 项 
satisfy 是 下 一 步 需 要 用 到 的 。 


6) 检查 ngx_http_core_ loc_conf t 结 构 体 中 的 satisfy 成 员 ， 如 果 值 为 


NGX_HTTP_SATISFY_ALL ( 即 nginx.conf 文 件 中 配置 了 satisfy all 参 


数 ) ， 则 意味 着 所 有 NGX_HTTP_ACCESS_PHASE 阶 段 的 handler 方 法 
必须 共同 作用 于 这 个 请 求 。 这 时 ，handler 方 法 的 返回 值 就 具有 不 同 的 
意义 了 。 如 果 它 的 返回 值 是 NGX_OK， 则 意味 着 这 个 handler 方 法 所 在 
的 HTTP 模 块 认为 当前 请 求 是 具备 访问 权限 的 ， 需 要 再 次 检查 
NGX_HTTP_ACCESS_PHASE 阶 段 的 下 一 个 HTTP 模 块 的 handler 方 法 ， 

是 会 跳 到 第 4 步 执行 ， 反 之 ， 如 果 返 回 值 不 是 NGX_OK， 就 意味 着 当 
前 请 求 无 权 访 问 服务 ， 这 时 需要 跳 到 第 8 步调 用 
ngx_http_finalize_request 方 法 结束 请 求 ， 方 法 的 参数 也 就 是 这 个 返回 
值 。 


如 果 ngx_http_core_loc_conf t 结 构 体 中 的 satisfy 成 员 值 为 
NGX_HTTP_SATISFY_ANY ( 即 nginx.conf 文 件 中 配置 了 satisfy any 参 
数 ) ， 也 就 是 说 ， 并 不 强制 要 求 NGX_HTTP_ACCESS_PHASE 阶 段 的 
所 有 handler 方 法 必须 同时 起 作用 ， 那 么 这 时 handler 方 法 的 返回 值 又 具 
有 了 不 同 的 意义 。 如 果 该 返回 值 是 NGX_OK， 则 表示 第 2 步 执行 的 
handler 方 法 认为 这 个 请 求 有 权限 访问 服务 ， 而 且 不 用 再 调用 
NGX_HTTP_ACCESS_PHASE 阶 段 的 其 他 handler 方 法 了 上， 直接 跳 到 第 7 


步 执行 ， 如 果 返 回 值 是 NGX_HTTP FORBIDDEN 或 者 
NGX_HTTP UNAUTHORIZED， 则 表示 这 个 HTTP 模 块 的 handler 方 法 


认为 请 求 没 有 权限 访问 服务 ， 但 只 要 NGX_HTTP_ACCESS_PHASE 阶 


段 的 任何 一 个 handler 方 法 返回 NGX_OK 就 认为 请 求 合法 ， 所 以 后 续 的 

handler 方 法 可 能 会 更 改 这 一 结 末 。 这 时 将 请 求 的 access_code 成 员 设置 

为 handler 方 法 的 返回 值 ， 用 于 传递 当前 HTTP 模 块 的 处 理 结果 ， 然 后 跳 
到 第 4 步 执 行 下 一 个 handler 方 法 ， 如 采 返 回 值 为 其 他 值 ， 可 以 认为 请 求 
绝对 无 权 访问 服务 ， 则 跳 到 第 8 步 执行 。 


7) 上 面 已 经 解释 过 ， 在 satisfy any 配 置 下 ，handler 方 法 返回 
NGX_OK 时 意味 着 这 个 请 求 具备 访问 权限 ， 将 请 求 的 access_code 成 员 
置 为 0， 跳 到 第 1 步 执 行 。 


8) 调用 ngx_http_finalize_request 方 法 结束 请 求 。 


虽然 ngx_http_core_access_phase 方 法 有 些 复杂 ， 即 它 为 
NGX_HITP_ ACCESS_PHASE 阶 段 中 的 handler 方 法 的 返回 值 增加 了 过 
多 的 含义 ， 但 当 我 们 开发 的 HTTP 模 块 需要 处 理 请 求 的 访问 权限 时 ， 就 
会 发 现 ngx_http_core_access_phase 方 法 给 我 们 带 来 强大 的 功能 ， 可 以 实 
现 复 杂 的 权限 控制 。 


11.6.4 ngx_http_core_content phase 


ngx_http_core_content_phase 是 NGX_HTTP_CONTENT_PHASE 阶 
段 的 checker 方 法 ， 可 以 说 它 是 我 们 开发 HTTP 模 块 时 最 音 用 的 一 个 阶段 
了 了。 顾名思义 ，NGX_HTTP_CONTENT PHASE 阶段 用 于 真正 处 理 请 


求 的 内 容 。 其 余 10 个 阶段 中 各 HTTP 模 块 的 处 理 方法 都 是 放 在 全 局 的 
ngx_http_core_main_conf t 结 构 体 中 的 ， 也 就 是 说 ， 它 们 对 任何 一 个 
HTTP 请 求 都 是 有 效 的 。 但 在 NGX_HTTP_CONTENT_PHASE 阶 段 却 很 
自然 地 有 男 一 种 需求 ， 有 的 HTTP 模 块 可 能 仅 希 望 在 这 个 处 理 请 求 内容 
的 阶段 ， 仅 仅 针对 某 种 请 求 唯一 生效 ， 而 不 是 对 所 有 请 求生 效 。 例 

如 ， 仅 当 请 求 的 URI 匹 配 了 配置 文件 中 的 某 个 location 块 时 ， 再 根据 
location 块 下 的 配置 选择 一 个 HTTP 模 块 执行 它 的 handler 处 理 方法 ， 并 以 
此 替代 NGX_HTTP_CONTENT_PHASE 阶 段 的 其 他 handler 方 法 (这些 
handler 方 法 对 于 该 请 求 将 得 不 到 执行 ) 


既然 我 们 希望 请 求 在 NGX_HTTP_ CONTENT PHASE 阶段 的 
handler 方 法 仅 与 Jocation 相 关 ， 那 么 就 肯定 与 ngx_http_core_loc_conf t 结 
构 体 相关 了 ， 注 意 handler 成 员 : 


struct ngx_http_core_loc conf_s { 


ngx_http_handler_pt handler; 


这 个 handler 成 员 属 于 nginx.conf 中 匹配 了 请 求 的 location 块 下 配置 的 
HTTP 模 块 (当然 ， 如 果 请 求 匹 配 的 location 块 下 没有 配置 HTTP 模 块 处 
理 请 求 ， 那 么 这 个 handler 指 针 将 为 NULL 空 指针 ) 。 回 顾 一 下 第 3 章 中 


的 ngx_http_mytest 方 法 ， 它 正 是 在 某 个 location 下 检测 到 mytest 配 置 项 


后 ， 取 到 当前 location 下 的 ngx_http_core_loc_conf t 结 构 体 ， 并 把 handler 
成 员 设 置 为 希望 在 NGX_HTTP_CONTENT_PHASE 阶 段 处 理 请 求 的 


ngx_http_mytest_handler 方 法 的 。 


实际 上 ， 为 了 加 快 处 理 速度 ，HTTP 框 架 义 在 ngx_http_request_t 结 
构 体 中 增加 了 一 个 成 员 content_handler (参见 11.3.1 闻 ) ， 在 
NGX_HTTP_FIND_CONFIG_PHASE 阶 段 就 会 把 它 设 为 匹配 了 请 求 URI 
的 location 块 中 对 应 的 ngx_http_core_loc_conf t 结 构 体 的 handler 成 员 ( 参 
见 Nginx 源 代码 的 ngx_http_update_location_config 方 法 ) 。 


以 上 所 述 是 NGX_HTTP_CONTENT_PHASE 阶 段 的 特殊 之 处 ， 当 
然 ， 它 还 可 以 像 其 余 10 个 阶段 一 样 具备 全 局 生效 的 handler 方 法 ， 但 如 
果 设 置 了 content_handler 方 法 ， 会 优先 以 content_handler 为 准 ， 如 图 11- 
11 所 示 。 


下 面 详细 介绍 一 下 ngx_http_core_content_phase 方 法 是 如 何 处 理 
NGX_HTTP_CONTENT_PHASE 阶 段 的 请 求 的 。 


1) 首先 检测 ngx_http_request_t 结 构 体 的 content_handler 成 员 是 否 为 
空 ， 其 实 就 是 看 在 NGX_HTTP FIND_CONFIG_ PHASE 了 阶段 匹配 了 URI 
请 求 的 location 内 ， 是 否 有 HTTP 模 块 把 处 理 方法 设置 到 了 


i 


ngx_http_core_loc_conf t 结 构 体 的 handler 成 员 中 。 如 果 content_handler 


为 空 ， 则 跳 到 第 2 步 开 始 执行 全 局 有 效 的 handler 方 法 ;否则 仅 执行 
content_handler 方 法 ， 看 看 源 代 码 中 做 了 些 什 么 ， 如 下 所 示 。 


r->write_event_handler = ngx_http_request_empty_handler; 
ngx_http_finalize_request(r, r->content_handler(r)); 


其 中 ， 首 先 设置 hgx_http_request_t 结 构 体 的 write_event_handler 成 
员 为 不 做 任何 事 的 ngx_http_request_empty_handler 方 法 ， 也 就 是 告诉 
HTTP 框 架 再 有 可 写 事件 时 就 调用 ngx_http_request_empty_handler 直 接 
把 控制 权 交 还 给 事件 模块 。 为 何 要 这 样 做 呢 ? 因 为 HTTP 框 架 在 这 一 阶 
段 调用 HTTP 模 块 处 理 请 求 就 意味 着 接 下 来 只 希望 该 模块 处 理 请 求 ， 先 
把 write_event_handler 强 制 转化 为 ngx_http_request_empty_handler， 可 以 
防止 该 HTTP 模 块 异步 地 处 理 请 求 时 却 有 其 他 HTTP 模 块 还 在 同时 处 理 
可 写 事 件 、 回 客户 端 发 送 啊 应 。 接 下 来 调用 content_handler 方 法 处 理 请 
求 ， 并 把 它 的 返回 值 作为 参数 传递 给 ngx_http_finalize_request 方 法 来 结 
束 请 求 。ngx_http_finalize_request 方 法 是 非常 复杂 的 ， 它 会 根据 引用 计 
数 来 确定 目 己 的 行为 ,具体 参见 11.10.6 字 。 


2) 在 没有 content_handler 方 法 时 ， 又 回 到 了 我 们 惯用 的 方式 ， 首 
先 根据 phase_handler 序 号 调用 handler 处 理 方 法 ， 检 测 它 的 返回 值 ， 当 返 
回 值 为 NGX_DECLINED 时 跳 到 第 4 步 ， 否 则 跳 到 第 3 步 执行 。 


3) 如 果 NGX_ HTTP CONTENT PHASE 阶 段 中 全 局 的 handler 方 法 
没有 返回 NGX_DECLINED， 则 意味 着 不 再 执行 该 阶段 的 其 他 handler 方 


法 。 因 此 ， 这 时 简单 地 以 handler 方 法 作为 参数 调用 
ngx_http_finalize_request 结 束 请 求 即 可 。 同 时 ， 
ngx_http_core_content_phase 方 法 返回 NGX_OK， 表 示 归 还 控制 权 给 事 
件 模 块 。 


[检查 匹配 了 请 求 网 卫 4 否 存在 content_handle 访 法 | 
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[ 不 存在 content_handle 访 法 ] 


[存在 content_handler 方 法 ] 


1 ) 调用 content_handler 


方法 并 结束 请 求 


2) 调用 HTTP 模 块 实现 的 


handler 处 理 方 法 
[检查 handle 广 法 的 返回 值 ] 


[返回 值 不 是 NGX_DECLINED] 
[返回 NGX_DECLINED] 3) 调用 ngx_http_finalize _request 


结束 请 求 


4 ) 转 到 下 一 


ngx_http_phase_handler_t 处 理 方法 
[ 今 查 ngx_http_phase_handler 1 的 checker 是 否 实现 ] 


Cy [checker 方 法 存在 ] 


[checker 方 法 不 存在 , 检查 请 求 的 URI] 5 ) phase_handler++ 并 返回 


NGX_AGAIN 


[请 求 的 URI 以 /结尾 ] 


6) 调用 ngx_http_finalize__request 


结束 请 求 ， 返 回 403 


7) 调 用 ngx_http_finalize _request 


结束 请 求 ， 返 回 404 


图 11-11 ngx_http_core_content_phase 方 法 的 流程 


4) 虽然 handler 方 法 返回 了 NGX_DECLINED， 表 示 和 希望 执行 本 阶 
段 的 下 一 个 handler 方 法 ， 但 是 当前 的 handler 方 法 是 否 已 经 是 最 后 一 个 


handler 方 法 了 呢 ? 这 需要 进行 检测 ， 首 先 转 到 数组 中 的 下 一 个 handler 
方法 ， 检 测 其 checker 方 法 是 否 存在 ， 若 存在 ， 则 跳 到 第 5 步 执行 ， 若 不 
存在 ， 则 结束 请 求 ， 但 需要 根据 URI 确 定 返 回 什 么 样 的 HITP 啊 应 ， 如 
果 URI 是 以 “结尾 ， 则 跳 到 第 6 步 执 行 ， 否 则 跳 到 第 7 步 执行 。 


5) 既然 handler 方 法 返回 NGX_DECLINED 和 希望 执行 下 一 个 handler 
方法 ， 那 么 这 一 步 把 请 求 的 phase_handler 序 号 加 1， 
ngx_http_core_content_phase 方 法 返回 NGX_AGAIN， 表 示 锅 望 HTTP 框 
架 立 刻 执行 下 一 个 handler 方 法 。 


6) 以 NGX_HTTP FORBIDDEN 作 为 参数 调用 
ngx_http_finalize_request 方 法 ， 表 示 结 束 请 求 并 返回 403 销 误 码 。 同 
时 ，ngx_http_core_content_phase 方 法 返回 NGX_OK， 表 示 交 还 控制 权 
给 事件 模块 。 


7) 以 NGX_HTTP_ NOT_FOUND 作 为 参数 调用 
ngx_http_finalize_request 方 法 ， 表 示 结 束 请 求 并 返回 404 销 误 码 。 同 
时 ，ngx_http_core_content_phase 方 法 返回 NGX_OK， 表 示 交 还 控制 权 
给 事件 模块 。 


NGX_HTTP _ CONTENT PHASE 阶段 是 各 HTTP 模 块 最 常 介 入 的 阶 
段 。 只 有 对 ngx_http_core_content_phase 方 法 的 流程 足够 熟悉 ， 才 能 实 
现 复杂 的 功能 


@ 注意 ”从 ngx_http_core_content_phase 方 法 中 可 以 看 到 ， 请 求 
在 第 10 个 阶段 NGX_HTTP_CONTENT_PHASE 后 ， 并 没有 去 调用 第 11 
个 阶段 NGX_HTTP_LOG_PHASE 的 处 理 方 法 ， 通 过 比较 11.6 节 的 其 他 
checker 方 法 ， 就 会 发 现 它 与 之 前 的 方法 都 不 同 。 事 实 上 ， 记 录 访 问 日 
志 是 必须 在 请 求 将 要 结束 时 才能 进行 的 ， 因 此 ， 
NGX_HTTP_LOG_PHASE 阶 段 的 回调 方法 在 11.10.2 市 介绍 的 
ngx_http_free_request 方 法 中 才 会 调用 到 。 


11.7 ”subrequest 与 post 请 求 


从 11.6 节 中 可 以 看 到 ，HTTP 框 架 无 论 是 调用 
ngx_http_process_request 方 法 〈 首 次 从 业务 上 处 理 请 求 ) 还 是 
ngx_http_request_handler 方 法 〈TCP 连 接 上 后 续 的 事件 触发 时 ) 处 理 请 
求 ， 最 后 都 有 一 个 步骤 ， 就 是 调用 ngx_http_run_posted_requests 方 法 处 
理 post 请 求 《如 图 11-5 中 的 第 8 步 、 图 11-7 中 的 第 4 步 ) 。 那 么 ， 什 么 是 
post 请 求 ? 为 什么 要 定义 post 请 求 ? post 请 求 义 是 怎样 实现 于 HTTP 框 架 
中 的 呢 ? 本 和 内 容 将 回答 这 3 个 问题 。 


Nginx 使 用 的 完全 无 阻 罕 的 事件 驱动 框 染 苹 难 以 编写 功能 复 洒 的 模 
块 的 ， 可 以 想见 ， 一 个 请 求 在 处 理 一 个 TCP 连 接 时 ， 将 需要 处 理 这 个 连 
接 上 的 可 读 、 可 写 以 及 定时 右 事 件 ， 而 可 读 事件 中 义 包 含 连 接 建 立成 
功 、 连 接 天 闭 事 件 ， 正 常 的 可 读 事件 在 接收 到 HTTP 的 不 同 部 分 时 叉 要 
做 不 同 的 处 理 ， 这 就 比较 复杂 了 “。 如 果 一 个 请 求 同 时 需要 与 多 个 上 游 
服务 器 打交道 ， 同 时 处 理 多 个 TCP 连 接 ， 那 么 它 需要 处 理 的 事件 就 太 多 
了 ， 这 种 复杂 上 度 会 使 得 模块 难以 维护 。Nginx 解 决 这 个 问题 的 手段 就 是 
第 5 章 中 介绍 过 的 subrequest 机 制 。 


subrequest 机 制 有 以 下 两 个 特点 : 


-从 业务 上 把 一 个 复杂 的 请 求 拆 分 成 多 个 子 请 求 ， 由 这 些 子 请 求 共 
同 合作 完成 实际 的 用 户 请 求 。 


:每 一 个 HTTP 模 块 通常 只 需要 关心 一 个 请 求 ， 而 不 用 试图 掌握 派生 
出 的 所 有 子 请 求 ， 这 极 大 地 降低 了 模块 的 开发 复杂 度 。 


这 两 个 特点 使 得 用 户 可 以 通过 开发 多 个 功能 相对 单一 独立 的 模 
块 ， 来 共同 完成 复杂 的 业务 。 


post 请 求 的 设计 就 是 用 于 实现 subrequest 子 请 求 机 制 的 ， 如 果 一 个 
请 求 具备 了 post 请 求 ， 并 且 HTTP 框 架 保证 post 请 求 可 以 在 当前 请 求 执行 
完毕 后 获得 执行 机 会 ， 那 么 subrequest 功 能 就 可 以 实现 了 。 子 请 求 的 设 
计 在 数据 结构 上 是 通过 ngx_http_request_t 结 构 体 的 3 个 成 员 
(posted_requests、parent、main) 来 保证 的 。 下 面 看 一 下 表示 单 辐 链表 
的 posted_requests 成 员 ， 它 的 类 型 是 ngx_http_posted_request_t 结 构 体 ， 
如 下 所 不 


typedef struct ngx_http_posted request s ngx_http_posted request_t; 
struct ngx_http_posted request s { 
// 指向 当前 待 处 理子 请 求 的 


ngx_http_request_t 结 构 体 


ngx_http_request_t *request,; 
// 指向 下 一 个 子 请 求 ， 如 果 没 有 ， 则 为 


NULL 空 指针 


ngx_http_posted request _t *next,; 


这 样 ， 通 过 posted_requests 了 驶 把 各 个 子 请 求 以 单 回 链表 的 数据 结构 
形式 组 织 起 来 了 。 


ngx_http_request_t 结 构 体 中 的 parent 指 向 了 当前 子 请 求 的 父 请 求 ， 
这 为 子 请 求 阿 前 寻找 父 请 求 提 供 了 可 能 性 。 


ngx_http_request_t 结 构 体 中 的 main 成 员 始 终 指 向 一 系列 有 亲缘 关系 
的 请 求 中 的 唯一 的 那个 原始 请 求 。 我 们 可 以 在 任何 一 个 子 请 求 中 通过 
main 成 员 找到 原始 请 求 ， 而 无 论 怎样 执行 子 请 求 ， 都 是 围绕 着 main 指 
器 的 原始 请 求 进行 的 ， 在 图 11-12 中 可 以 看 到 。 


[检查 Ngin : 让 


ginx 本 客户 端的 连接 ] 


[TCP 连 接 已 销毁 ] 


[与 客户 端的 TCP 连 接 存在 ] 


1 ) 获取 原始 请 求 posted_requests 


链表 的 首 个 post 请 求 
[ 检 查 post 请 求 是 及 存在 |] 


| post 请 求 不 存在 | 


| 具有 post 请 求 | 


2) 将 原始 请 求 的 posted_requests 
成 员 指 问 链 表 | 的 下 = 四 个 post 请 求 


3 ) 执 行当 前 post 请 求 的 
write_event_handler 方 法 


图 11-12 ”post 请 求 的 执行 


ngx_http_request_t 结 构 体 中 的 count 成 员 将 作为 引用 计数 ， 每 当 派 
生出 子 请 求 时 ， 原 始 请 求 的 count 成 员 都 会 加 1， 在 真正 销毁 请 求 前 ， 可 
以 通过 检查 count 成 员 是 否 为 0 以 确认 是 否 销毁 原始 请 求 ， 这 样 可 以 做 到 
唯 有 所 有 的 子 请 求 都 结束 时 ， 原 始 请 求 才 会 销毁 ， 内 存 池 、TCP 连 接 等 
资源 才 会 释放 。 


对 于 subrequest 子 请 求 的 用 法 ， 可 参见 5.4 节 ， 这 里 不 再 著述 。 图 11- 
12 展 示 ngx_http_run_posted_requests 方 法 是 怎么 执行 一 个 请 求 的 post 请 
求 的 ， 也 就 是 如 果 一 个 请 求 拥有 子 请 求 时 ， 子 请 求 是 怎么 被 调度 的 。 


从 图 11-12 中 可 以 看 到 ， 在 执行 某 一 个 请 求 时 ， 它 的 所 有 post 请 求 
都 可 能 被 执行 一 这。 下 面 详细 介绍 以 上 流程 。 


1) 首先 检查 连接 是 否 已 销毁 ， 如 果 连 接 被 销毁 ， 怠 结束 
ngx_http_run_posted_requests 方 法 ， 否 则 根据 ngx_http_request_t 结 构 体 
中 的 main 成 员 找 到 原始 请 求 ， 这 个 原始 请 求 的 posted_requests 成 员 指 问 
竺 处 理 的 post 请 求 组 成 的 单 链表 ， 如 果 posted_requests 指 各 NULL 空 指 
针 ， 则 结束 ngx_http_run_posted_requests 方 法 ， 否 则 取出 链表 中 首 个 指 
向 post 请 求 的 指针 ， 并 跳 到 第 2 步 执 行 。 


2) 将 原始 请 求 的 posted_requests 指 针 指 向 链表 中 下 一 个 post 请 求 
(通过 第 1 个 post 请 求 的 next 指 针 可 以 获得 ) ， 当 然 ， 下 一 个 post 请 求 有 


可 能 不 存在 ， 这 在 下 一 次 循环 中 束 会 检测 到 。 


3) 调用 这 个 post 请 求 ngx_http_request_t 结 构 体 中 的 
write_event_handler 方 法 。 为 什么 不 是 执行 read_event_handler 方 法 呢 ? 
原因 很 简单 ， 子 请 求 不 是 被 网 络 事件 驱动 的 ， 因 此 ， 执 行 post 请 求 时 就 
相当 于 有 可 写 事件 ， 由 Nginx 主 动 做 出 动作 。 


在 本 下 可 以 看 到 ，HTTP 框 架 在 处 理 一 个 请 求 时 ， 如 果 发 现 其 有 子 
请 求 则 一 定 会 处 理 。 通 过 修改 原始 请 求 的 posted_requests 指 针 ， 甚 至 还 
可 以 控制 从 哪 一 个 子 请 求 开始 执行 ， 当 然 ， 直 接 修改 HTTP 框 染 中 的 成 
员 很 容易 出 氏 ， 一 定 要 慎重 。 


11.8 处理 HTTP 包 体 


本 节 开 始 介绍 HTTP 框 架 为 HTTP 模 块 提供 的 工具 方法 。 在 HTTP 
中 ， 一 个 请 求 通常 由 必 选 的 HTTP 请 求 行 、 请 求 头 部 ， 以 及 可 选 的 包 体 
组 成 ， 因 此 ， 在 接收 完 HTTP 头 部 后 ， 就 可 以 开始 调用 各 HTTP 模 块 处 
理 请 求 了 ( 见 11.6 节 ) ， 然 后 由 HTTP 模 块 决定 如 何 处 理 包 体 。 


HITTP 框 架 提供 了 两 种 方式 处 理 HITP 包 体 ， 当 然 ， 这 两 种 方式 保 
持 了 完全 无 阻塞 的 事件 驱动 机 制 ， 非 常 高 效 。 第 一 种 方式 束 是 把 请 求 
中 的 包 体 接收 到 内 存 或 者 文件 中 ， 当 然 ， 由 于 包 体 的 长 度 是 可 变 的 ， 
同时 内 存 又 是 有 限 的 ， 因 此 ， 一 般 都 是 将 包 体 存放 到 文件 中 (本 市 不 
会 详细 讨论 包 体 的 存储 策略 ) 。 第 二 种 方式 是 选择 丢弃 包 体 ， 注 意 ， 
丢弃 不 等 于 可 以 不 接收 包 体 ， 这 样 做 可 能 会 导致 客户 端 出 现 发 送 请 求 
超时 的 错误 ， 所 以 ， 这 个 丢弃 只 是 对 于 HTTP 模 块 而 言 的 ，HTTP 框 染 
还 是 需要 “尽职 尽责 ”地 接收 包 体 ， 在 接收 后 直接 丢弃 。 


本 市 将 会 过 到 一 个 问题 ， 这 个 问题 需要 用 请 求 ngx_http_request_t 结 
构 体 中 的 count 引 用 计数 解决 。 举 个 例子 ，HTTP 模 块 在 处 理 请 求 时 ， 接 
收 包 体 的 同时 可 能 还 需要 处 理 其 他 业务 ， 如 使 用 upstream 机 制 与 男 一 台 
服务 器 通信 ， 这 样 两 个 动作 都 不 古 一 次 调度 可 以 完成 的 ， 它 们 各 目 都 
可 能 需要 多 次 调度 才能 完成 ， 那 么 在 其 中 一 个 动作 出 现 错误 导致 请 求 


失败 时 ， 如 采 销 毁 请 求 可 能 会 导致 为 一 个 动作 出 现 产 重 错误 ， 和 皇 么 
办 ? 这 时 就 需要 用 到 引用 计数 了 。 


在 HTTP 模 块 中 每 进行 一 类 新 的 操作 ， 包 括 为 一 个 请 求 添 加 新 的 事 
件 ， 或 者 把 一 些 已 经 由 定时 器 、epoll 中 移 除 的 事件 重新 加 入 其 中 ， 都 
需要 把 这 个 请 求 的 引用 计数 加 1。 这 是 因为 需要 让 HTTP 框 架 知 道 ， 
HTTP 模 块 对 于 该 请 求 有 独立 的 异步 处 理 机 制 ， 将 由 该 HTTP 模 块 决定 
这 个 操作 什么 时 候 结束 ， 防 止 在 这 个 操作 还 未 结束 时 HTTP 框 架 却 把 这 
个 请 求 销毁 了 (如 其 他 HTTP 模 块 通过 调用 ngx_http_finalize_request 方 
法 要 求 HTTP 框 架 结 束 请 求 ) ， 导 致 请 求 出 现 不 可 知 的 严重 错误 。 这 就 
要 求 每 个 操作 在 “认为 ” 目 身 的 动作 结束 时 ， 痢 得 最 终 调用 到 
ngx_http_close_request 方 法 ， 该 方法 会 目 动 检查 引用 计数 ， 当 引用 计数 
为 0 时 才 真 正 地 销毁 请 求 。 实 际 上 ， 很 多 结束 请 求 的 方法 最 后 一 定 会 调 
用 到 ngx_http_close_request 方 法 (参见 11.10.3 闻 ) 。 


由 于 HTTP 包 体 是 可 变 长 度 的 ， 接 收 包 体 可 能 导致 HTTP 框 染 将 TCP 
连接 上 的 读 事 件 再 次 添加 到 epoll 和 定时 器 中 ， 表 示 硕 望 事 件 驱 动机 制 
发 现 TCP 连 接 上 接收 到 全 部 或 者 部 分 HTTP 包 体 时 ， 回 调 相 应 的 方法 读 
取 确 接 字 缓 神 区 上 的 TCP 流 ， 这 时 必须 把 请 求 的 引用 计数 加 1， 这 在 图 
11-13 的 第 1 步 中 就 可 以 看 到 。 类 似 的 ， 在 第 5 章 介绍 的 subrequest 子 请 求 
的 使 用 方法 中 ， 派 生子 请 求 也 是 独立 的 动作 ， 它 会 向 epoll 和 定时 右 中 
添加 新 的 事件 ， 引 用 计数 也 会 加 1， 而 upstream 试 图 连接 新 的 服务 器 ， 


它 同 样 也 需要 把 当前 请 求 的 引用 计数 加 1。 当 这 类 操作 结束 时 ， 如 
HTTP 包 体 全 部 接收 完毕 时 ， 务 必 调 用 或 者 间接 地 调用 
ngx_http_close_request 方 法 ， 把 引用 计数 减 1， 这 才能 使 引用 计数 机 制 
正常 工作 。 


@@ 注音 引用 计数 一 般 都 作用 于 这 个 请 求 的 原始 请 求 上 ， 因 
此 ， 在 结束 请 求 时 统一 检查 原始 请 求 的 引用 计数 就 可 以 了 。 当 然 ， 目 
前 的 HTTP 框 架 也 要 求 我 们 必须 这 样 做 ， 因 为 ngx_http_close_request 方 
法 只 是 把 原始 请 求 上 的 引用 计数 减 1。 对 应 到 代码 就 是 操作 <->main- 


和 /AN 


>count 成 员 ， 其 中 r 是 请 求 对 应 的 ngx_http_request_t 结 构 体 。 


下 面 来 看 看 HTTP 框 架 提供 的 方法 是 如 何 使 用 的 ， 接 收 包 体 的 方法 
其 实在 3.6.4 节 中 已 经 讲 过 ， 再 来 回顾 一 下 。 


ngx_int_t ngx_http_read_client_request_body(ngx_http_request_t *r, 
ngx_http_client_ body_handler_pt post_handler); 


调用 了 ngx_http_read_client_request_body 方 法 就 相当 于 启动 了 接收 
包 体 这 一 动作 ， 在 这 个 动作 完成 后 ， 就 会 回调 HTTP 模 块 定 义 的 
post_handler 方 法 。post_handler 是 一 个 函数 指针 ， 如 下 所 示 。 


typedef void (*ngx_http_client body_handler_pt) (ngx_http_request t *r); 


而 决定 丢弃 包 体 时 ，HTTP 框 架 提供 的 方法 是 
ngx_http_discard_request_body， 如 下 所 示 。 


ngx_int_t ngx_http_discard_redquest_body(ngx_http_redquest _t *r) 


当然 ， 它 是 不 需要 再 让 HTTP 模 块 定义 类 似 post_handler 的 回调 方法 
的 ， 当 丢弃 包 体 后 ，HTTP 框 架 会 目 动 调用 ngx_http_finalize_request 方 
法 把 引用 计数 减 1， 详 见 11.8.2 节 。 


在 11.8.1 节 中 将 会 讨论 HTTP 框 架 是 怎样 实现 
ngx_http_read_client_request_body 方 法 的 ， 而 在 11.8.2 廊 中 则 会 讨论 
ngx_http_discard_request_body 方 法 的 实现 ， 由 于 这 两 个 方法 都 需要 被 事 
件 框 架 多 次 调度 ， 学 习 它 们 的 设计 方法 可 以 帮助 我 们 开发 高 效 的 Nginx 
模块 。 


11.8.1 接收 包 体 


在 讨论 ngx_http_read_client_request_body 方 法 的 实现 方式 前 ， 先 来 
看 一 下 用 于 保存 HTTP 包 体 的 结构 体 ngx_http_request_body_t， 如 下 所 


人 小? 


typedef struct { 
// 存放 


HTTP 包 体 的 临时 文件 


ngx_temp_file t *temp_file; 
/* 接 收 


HTTP 包 体 的 缓冲 区 链表 。 当 包 体 需要 全 部 存放 在 内 存 中 时 ， 如 果 一 块 


ngx_buf_t 缓 冲 区 无 法 存放 完 ， 这 时 就 需要 使 


ngx_chain_t 链 表 来 存放 


ngx_chain_t *bufs,; 


// 直接 接收 
HTTP 包 体 的 缓存 


ngx_buf_t *buf， 
/* 根 据 


content-length 头 部 和 已 接收 到 的 包 体 长 度 ， 计 算出 的 还 需要 接收 的 包 体 长 度 


二 
off_t rest， 
// 该 缓冲 区 链表 存放 着 将 要 写 入 文件 的 包 体 


ngx_chain_t *to_write' 


/*HTTP 包 体 接收 完毕 后 执行 的 回调 方法 ， 也 就 是 


ngx_http_read_client_request_body 方 法 传递 的 第 


2 个 参数 


* 
/ 

ngx_http_client_body_handler_pt post_handler; 
} ngx_http_request_body_t; 


这 个 ngx_http_request_body_t 结 构 体 束 存 放 在 保存 大 请 求 的 
ngx_http_request_t 结 构 体 的 request_body 成 员 中 ， 授 收 HTTP 包 体 就 是 
绕 厦 这 个 数据 结构 进行 的 。 


上 文 说 过 ， 在 接收 较 大 的 包 体 时 ， 无 法 在 一 次 调度 中 人 完成。 通俗 
地 讲 ， 就 是 接收 包 体 不 是 调用 一 次 ngx_http_read_client_request_body 方 
法 就 能 完成 的 。 但 是 HTTP 框 染 硕 望 对 于 它 的 用 户 ， 也 就 是 HTTP 模 块 
而 言 ， 接 收 包 体 时 只 需要 调用 一 次 ngx_http_read_client_request_body 方 
法 就 好 ， 这 时 就 需要 有 另 一 个 方法 在 ngx_http_read_client_request_body 
没 接收 到 完整 的 包 体 时 ， 如 来 连 接 上 再 次 接收 到 包 体 束 被 调用 ， 
方法 就 是 ngx_http_read_client_request_body_handler 。 


ngx_http_read_client_request_body_handler 方 法 对 于 HTTP 模 块 是 不 
可 见 的 ， 它 在 “幕后 ”工作 。 当 继续 接收 发 目 客 户 端的 包 体 时 ， 将 由 它 
来 处 理 。 可 见 ， 它 与 ngx_http_read_client_request_body 方 法 有 很 多 共通 
之 处 ， 它 们 都 会 去 试图 读 取 连接 套 接 字 上 的 缓冲 区 ， 把 它们 共性 的 部 
分 提取 出 来 构成 ngx_http_do_read_client_request_body 方 法 ， 它 负责 具体 
的 读 取 包 体 工 作 。 本 市 的 内 容 束 在 于 说 明 这 3 个 方法 的 流程 。 


图 11-13 为 ngx_http_read_client_request_body 方 法 的 流程 图 ， 在 该 图 
中 同时 可 以 看 到 ngx_http_request_t 结 构 体 中 的 request_body 成 员 是 如 何 
分 配 和 使 用 的 。 


) 原始 请 求 的 引用 计数 加 1 
[检查 是 否 操作 过 请 求 的 包 体 ] 


[未 操作 过 包 体 ] 


3 ) 分 配 用 于 接收 包 体 的 


request_body 成 员 [已 经 做 过 放弃 包 体 或 者 接收 包 体 的 操作 ] 
[检查 请 求 的 content- length 头 部 ] 


[content_length 小 于 或 等 于 0] 


[content Jength 大 于 0] 


4) 设置 接收 完全 部 包 体 后 的 


post_handler 回 调 方法 
[从 在 已 经 读 取 到 的 包 体 长 度 ] 


[已 接收 到 的 包 体 长 度 大 于 或 等 于 content_length] 


[还 没有 接收 到 全 部 的 包 体 , 检查 headerin 缓冲 区 是 否 可 接收 全 部 包 体 ] 


[headerin 缓 冲 区 无 法 存放 全 部 包 体 ] 


2 ) 调 用 HTTP 模 块 要 求 回 调 的 


[接收 头 部 的 heoder in 缓冲 区 可 以 存放 完整 的 包 体 ] pos ane HE 
5 ) 在 request_body 
上 分 配 用 于 接收 包 体 的 缓冲 区 


6) 设置 后 续 接 收 连接 上 TCP 流 的 
read_event_ handler 方 法 


7 ) 调用 ngx_do_read_client_request_body 


方法 接收 包 体 


@ 


图 11-13 ”ngx_http_read_client_request_body 方 法 的 流程 图 


图 11-13 把 ngx_http_read_client_request_body 方 法 的 主要 流程 概括 为 
7 个 步骤 ， 下 面 详细 说 明 一 下 。 


1) 首先 把 该 请 求 对 应 的 原始 请 求 的 引用 计数 加 1。 这 同时 是 在 要 
求 每 一 个 HTTP 模块 在 传 入 的 post_handler 方 法 被 回调 时 ， 务 必 调 用 类 似 
ngx_http_finalize_request 的 方法 去 结束 请 求 ， 否 则 引用 计数 会 始终 无 法 
清 零 ， 从 而 导致 请 求 无 法 释放 。 


分 查 请 求 ngx_http_request_t 结 构 体 中 的 request_body 成 员 ， 如 果 它 
已 经 被 分 配 过 了 ， 证 明 已 经 读 取 过 HTTP 包 体 了 ， 不 需要 再 次 读 取 一 
所 ， 这 时 跳 到 第 2 步 执行 ， 再 检查 请 求 ngx_http_request_t 结 构 体 中 的 
discard_body 标 志 位 ， 如 果 discard_body 为 1， 则 证 明 曾 经 执行 过 丢弃 包 
体 的 方法 ， 现 在 包 体 正在 被 丢弃 中 ， 仍 然 跳 到 第 2 步 执行 。 只 有 这 两 个 
条 件 都 不 满足 ， 才 说 明 真正 需要 接收 HTTP 包 体 ， 这 时 跳 到 第 3 步 执 


一 


4 


2) 这 一 步 将 直接 执行 各 HTTP 模 块 提供 的 post_handler 回 调 方 法 ， 


接着 ，ngx_http_read_client_request_body 方 法 返回 NGX_OK 。 


3) 分 配 请 求 的 ngx_http_request_t 结 构 体 中 的 request_body 成 员 (之 
前 request_body 是 NULL 空 指针 ) ， 准 备 接收 包 体 。 


4) 检查 请 求 的 content-length 头 部 ， 如 果 指 定 了 包 体 长 度 的 content- 
length 字 段 小 于 或 等 于 0， 当 然 不 用 继续 接收 包 体 ， 跳 到 第 2 步 执行 ， 如 
果 content-length 大 于 0， 则 意味 着 继续 执行 ， 但 HTTP 模 块 定义 的 


post_handler 方 法 不 会 知道 在 哪 一 次 事件 的 触发 中 会 被 回调 ， 所 以 先 把 
它 设置 到 request_body 结 构 体 的 post_handler 成 员 中 。 


5) 注意 ， 在 11.5 节 描述 的 接收 HTTP 头 部 的 流程 中 ， 是 有 可 能 接收 
到 HITP 包 体 的 。 首 移 我 们 需要 检查 在 header in 缓冲 区 中 已 经 接收 到 的 
包 体 长 度 ， 确 定 其 是 否 大 于 或 者 等 于 content-length 头 部 指定 的 长 度 ， 如 
果 大 于 或 等 于 则 说 明 已 经 接收 到 完整 的 包 体 ， 这 时 跳 到 第 2 步 执行 。 


当 上 述 条 件 不 满足 时 ， 再 检查 header_ ip 缓冲 区 里 的 剩余 空闲 空间 
是 否 可 以 存放 下 全 部 的 包 体 (content-length 头 部 指定 ) ， 如 果 可 以 ， 就 
不 用 分 配 新 的 包 体 缓冲 区 当 费 内 存 了， 直接 跳 到 第 6 步 执行 。 


当 以 上 两 个 条 件 都 不 满足 时 ， 说 明确 实 需要 分 配 用 于 接收 包 体 的 
缓冲 区 了 。 缓 冲 区 长 度 由 nginx.con{ 文 件 中 的 client_body_buffer_size 配 
置 项 指定 ， 缓 冲 区 就 在 ngx_http_request_body_t 结 构 体 的 buf 成 员 中 存放 
着 ， 同 时 ，bufs 和 to_write 这 两 个 缓冲 区 链表 首部 也 指向 该 buf 。 


6) 设置 请 求 ngx_http_request_t 结 构 体 的 read_event_handler 成 员 为 


上 面 介 绍 过 的 ngx_http_read_client_request_body_handler 方 法 ， 它 意味 着 
如 采 epol 再 次 检测 到 可 读 事件 或 者 读 事 件 的 定时 夯 超 时 ，HTTP 框 以 将 
调用 ngx_http_read_client_request_body_handler 方 法 处 理 ， 该 方法 所 做 的 
工作 参见 图 11-15 。 


7) 调用 ngx_http_do_read_client_request_body 方 法 接收 包 体 。 该 方 
法 的 意义 在 于 把 客户 端 与 Nginx 之 间 TCP 连 接 上 套 接 字 缓 冲 区 中 的 当前 
字符 流 全 部 读 出 来 ， 并 判断 是 否 需 要 写 入 文件 ， 以 及 是 否 接 收 到 全 前 
的 包 体 ， 同 时 在 接收 到 完整 的 包 体 后 激活 post_handler 回 调 方 法 ， 如 图 


11-14 所 示 。 


[检查 request .OO 接收 包 体 缓冲 区 ] 


[缓冲 区 写 满 ] 


[缓冲 区 上 还 有 空闲 空间 ] 


1 ) 将 缓冲 区 中 数据 
写 入 临时 文件 


2) 重 置 ngx_buf t+ 缓冲 区 里 的 


os 、last 参 


[ 仍 有 可 接收 的 字符 流 ] 

3) 将 TCP 连 接 套 接 字 上 的 
字符 流 读 取 到 缓冲 区 

[检查 recv 方 法 的 返回 值 ] 


[出 现 错误 或 者 客户 端 关 闭 了 连接 ] 


[接收 到 字符 流 ] 


4) 设置 error 标 志 位 为 1， 


5 ) 根据 接收 内 容 修 改 


返回 错误 码 400 
缓冲 区 的 last 参 数 下 国信 


[ 套 接 字 缓 冲 区 中 没有 可 读数 据 ] 


[已 接收 到 全 部 的 包 体 ,检查 定时 器 中 是 否 还 在 监控 读 事件 ] 


( 
到 定时 器 
< 在 定时 器 中 | 


[ 读 事 件 还 在 定时 器 中 ] 「 读 事件 


8 ) 将 读 事 件 从 定时 器 
中 删除 7 ) 将 读 事 件 添加 到 epoll 
并 返回 NGX_AGAIN 


9) 将 缓冲 区 剩余 内 容 
写 入 临时 文件 


10) 重新 设置 后 续 接收 连接 上 TCP 流 的 


read_event_handler 方 法 


11) 调用 HTTP 模 块 要 求 回 调 的 
)ost _handler 方 法 


图 11-14 ngx_http_do_read_client_request_body 方 法 的 流程 图 


图 11-14 中 列 出 的 ngx_http_do_read_client_request_body 方 法 流程 稍 
显 复杂 ， 下 面 详细 解释 一 下 这 11 个 步 又 。 


1) 首先 检查 请 求 的 request_body 成 员 中 的 buf 缓 冲 区 ， 如 果 缓 冲 区 
还 有 空 几 的 空间 ， 则 跳 到 第 3 步 读 取 内 核 中 套 接 字 缓 冲 区 里 的 TCP 字 符 
流 ， 如 果 绥 冲 区 已 经 写 满 ， 则 调用 ngx_http_write_request_body 方 法 把 
绥 冲 区 中 的 字符 流 写 入 文件 。 


2) 通过 第 1 步 把 request_body 绥 冲 区 中 的 内 容 写 入 文件 后 ， 绥 冲 区 
束 可 以 重复 使 用 了 ， 只 需要 把 缓冲 区 ngx_buf _t 结 构 体 的 last 指 针 指 向 
start 指 针 ， 缓 冲 区 即 可 复 用 。 


3) 调用 封装 了 recv 的 方法 从 套 接 字 缓冲 区 中 读 取 包 体 到 绥 促 区 
中 。 如 果 recv 方 法 返回 错误 ， 或 者 客户 端 主 动 天 闭 了 连接 ， 则 跳 到 第 4 
步 执行 ， 如 果 读 取 到 内 容 ， 则 跳 到 第 5 步 执行 。 


4) 设置 ngx_http_request_t 结 构 体 的 error 标 志 位 为 1， 同 时 返回 
NGX_HTTP BAD REQUEST 错误 码 。 


5) 根据 接收 到 的 TCP 流 长 度 ， 修 改 缓冲 区 参数 。 例 如 ， 把 缓冲 区 
ngx_buf_t 结 构 体 的 last 指 针 加 上 接收 到 的 长 度 ， 同 时 更 新 request_body 
结构 体 中 表示 待 接收 的 剩余 包 体 长 度 的 rest 成 员 、 更 新 
ngx_http_request_t 结 构 体 中 表示 已 接收 请 求 长度 的 request_length 成 员 。 


根据 rest 成 员 检 查 是 否 接收 到 完整 的 包 体 ， 如 采 接 收 到 了 完整 的 包 
体 ， 则 跳 到 第 8 步 继 续 执 行 ， 否 则 查看 套 接 字 缓冲 区 上 是 否 仍然 有 可 读 
的 字符 流 ， 如 果 有 则 跳 到 第 1 步 继 续 接 收 包 体 ， 如 果 没 有 则 跳 到 第 6 
步 。 


6) 如 果 当 前 已 经 没有 可 读 的 字符 流 ， 同 时 还 没有 接收 到 完整 的 包 
体 ， 则 说 明 需 要 把 读 事 件 添 加 到 事件 模块 ， 等 待 可 读 事件 发 生 时 ， 事 
件 框架 可 以 再 次 调度 到 这 个 方法 接收 包 体 。 这 一 步 是 调用 
ngx_add_timer 方 法 将 读 事件 添加 到 定时 器 中 ， 超 时 时 间 以 nginx.conf 文 
件 中 的 client_body_timeout 配 置 项 参数 为 准 。 


7) 调用 ngx_handle_read_event 方 法 将 读 事件 添加 到 epoll 等 事件 收 
集 器 中 ， 同 时 ngx_http_do_read_client_request_body 方 法 结束 ， 返 回 


NOGOX_AGAIN 。 


8) 到 这 一 步 ， 表 明 已 经 接收 到 完整 的 包 体 ， 需 要 做 一 些 收尾 工作 
了 。 首 先 不 需要 检查 是 否 接收 HTTP 包 体 超 时 了 ， 要 把 读 事 件 从 定时 器 
中 取出 ， 防 止 不 必要 的 定时 融和 触发 。 这 一 步 会 检查 读 事 件 的 timer_set 标 
志 位 ， 如 果 为 1， 则 调用 ngx_del_timer 方 法 把 读 事件 从 定时 器 中 移 除 。 


9) 如 果 缓 冲 区 中 还 有 未 写 入 文件 的 内 容 ， 调 用 
ngx_http_write_request_body 方 法 把 最 后 的 包 体 内 容 也 写 入 文件 。 


10) 在 图 11-13 的 第 5 步 中 曾经 把 请 求 的 read_event_handler 成 员 设置 
为 ngx_http_read_client_request_body_handler 方 法 ， 现 在 既然 已 经 接收 到 
完整 的 包 体 了 ， 束 会 把 read_event_handler 设 为 ngx_http_block_reading 方 
法 ， 表 示 连 接 上 再 有 读 事 件 将 不 做 任何 处 理 。 


11) 执行 HTTP 模 块 提 供 的 post_handler 回 调 方法 后 ， 
ngX_http_do_read_client_request_body 方 法 结束 ， 返 回 NGX_OK。 


图 11-13 中 的 第 6 步 把 请 求 的 read_event_handler 成 员 设置 为 
ngx_http_read_client_request_body_handler 方 法 ， 从 11.6 节 的 图 11-7 可 以 
看 出 ， 这 个 请 求 连 授 上 的 读 事 件 触 发 时 的 回调 方法 
ngx_http_request_handler 会 调用 read_event_handler 方 法 ， 下 面 根据 图 11- 
15 来 看 看 这 时 ngx_http_read_client_request_body_handler 方 法 做 了 些 什 
人 o 


[ 读 事 件 未 超时 ] 


[ 读 事件 已 经 超时 ] 


1 ) 调用 ngx_http_finalize _request 
结束 请 求 并 发 送 408 响 应 


2 ) 调用 ngx_http_do_read_client _request_body 方 法 接收 包 体 


法 返回 值 ] 


[返回 值 大 于 或 等 于 300] 


[小 于 300] 


3) 以 上 一 步 返 回 值 为 参数 调用 
ngx_http _finalize _request 结束 请 求 


图 11-15 ”ngx_http_read_client_request_body_handler 方 法 的 流程 图 


简单 解释 一 下 图 11-15 中 的 3 个 步骤 。 


1) 首先 检查 连接 上 读 事 件 的 timeout 标 志 位 ， 如 果 为 1， 则 表示 接 
收 HTTP 包 体 超 时 ， 这 时 把 连接 ngx_connection_t 结 构 体 上 的 timeout 标 志 
位 也 置 为 1， 同 时 调用 ngx_http_finalize_request 方 法 结束 请 求 ， 并 发 送 
408 超 时 错误 码 。 如 果 没 有 超时 ， 则 跳 到 第 2 步 执行 。 


2) 调用 图 11-14 中 介绍 的 ngx_http_do_read_client_request_body 方 法 
接收 包 体 ， 检 测 这 个 方法 的 返回 值 ， 如 果 它 大 于 300， 那 么 一 定 表 示 硕 
望 返回 错误 码 。 例 如 ， 图 11-14 的 第 4 步 束 返回 了 400 错 误 码 ， 这 时 跳 到 
第 3 步 执行 ， 否 则 ngx_http_read_client_request_body_handler 方 法 结束 ， 
直接 返回 NGX_OK。 


3) 调用 ngx_http_finalize_request 方 法 结束 请 求 ， 第 2 个 参数 传递 的 


是 ngx_http_do_read_client_request_body 方 法 的 运 回 值 ， 评 见 11.10.6 字 。 


以 上 3 个 方法 完整 地 描述 了 HTTP 框 染 接 收 包 体 的 流程 ， 以 及 最 后 
如 何 执 行 HTTP 模 块 实现 的 post_handler 方 法 。 读 者 可 以 参照 它 再 看 看 第 
3 章 中 开发 HTTP 模 块 时 是 如 何 接 收 包 体 的 ， 相 信 经 过 本 章 的 分 析 ， 读 
者 会 对 这 一 机 制 有 新 的 认识 。 


11.8.2 ”放弃 接收 包 体 


对 于 HTTP 模 块 而 言 ， 放 弃 接收 包 体 束 古人 简 单 地 不 处 理 包 体 了 ， 可 
征 对 于 HTTP 框 架 而 言 ， 并 不 是 不 接收 包 体 束 可 以 的 。 因 为 对 于 客户 端 
而 言 ， 通 单 会 调用 一 些 阻 塞 的 发 送 方法 来 发 送 包 体 ， 如 采 HTTP 框 以 一 
直 不 接收 包 体 ， 会 导致 实现 上 不 够 健壮 的 客户 端 认为 服务 亏 超 时 无 啊 
应 ， 因 而 简单 地 关闭 连接 ， 可 这 时 Nginx 模 块 可 能 还 在 处 理 这 个 连接 。 
因此 ，HTTP 模 块 中 的 放弃 接收 包 体 ， 对 HTTP 框架 而 言 束 是 接收 包 
体 ， 但 是 接收 后 不 做 保存 ， 直 接 丢 弃 。 


HTTP 框 架 提 供 了 一 个 方法 一 ngx_http_discard_request_body 用 于 丢 
弃 包 体 ， 使 用 上 也 非常 简单 ， 直 接 调 用 这 个 方法 束 可 以 了 ， 不 像 11.8.1 
节 中 接收 包 体 一 样 还 需要 一 个 回调 方法 。 下 面 先 来 看 看 
ngx_http_discard_request_body 方 法 的 定义 。 


ngx_int_t ngx_http_discard _ request_body(ngx_http_request_t *r) 


可 以 看 到 ， 它 是 没有 post_handler 回 调 方法 的 ， 那 么 接收 完全 部 的 
包 体 后 怎么 办 呢 ? 很 简单 ， 在 图 11-18 的 第 3 步 就 是 接收 到 全 部 包 体 后 的 
动作 ， 其 代码 如 下 所 示 。 


ngx_http_finalize_request(r, NGX_DONE); 


这 里 实际 上 相当 于 把 原始 请 求 的 引用 计数 减 1 了 ， 当 然 ， 如 采 引 用 
计数 为 0 (如 HTTP 模 块 已 经 调用 过 结束 请 求 的 方法 ) ， 还 是 会 真正 结 
束 请 求 的 。 


放弃 接收 包 体 和 接收 包 体 的 实现 方式 是 极其 相似 的 ， 它 也 使 用 了 3 
个 方法 实现 ，HTTP 模 块 调用 的 ngx_http_discard_request_body 方 法 用 于 
第 一 次 启动 丢弃 包 体 动作 ， 而 ngx_http_discarded_request_body_handler 
是 作为 请 求 的 read_event_handler 方 法 的 ， 在 有 新 的 可 读 事 件 时 会 调用 它 
处 理 包 体 。ngx_http_read_discarded_request_body 方 法 则 是 根据 上 述 两 


个 方法 通用 部 分 提取 出 的 公共 方法 ， 用 来 读 取 包 体 且 不 做 任何 处 理 。 


下 面 看 看 ngx_http_discard_request_body 方 法 做 了 些 什 么 ， 如 图 11- 


16 所 示 。 


F 面 解释 一 下 图 11-16 中 所 列 的 7 个 步骤 。 


1) 首先 检查 当前 请 求 是 一 个 子 请 求 还 是 原始 请 求 。 为 什么 要 检查 
这 个 呢 ? 因 为 对 于 子 请求 而 言 ， 它 不 是 来 目 客 户 剖 的 请 求 ， 所 以 不 存 
在 处 理 HTTP 请 求 包 体 的 概念 。 如 果 当 前 请 求 是 原始 请 求 ， 则 跳 到 第 2 
步 中 继续 执行 ， 如 有 果 它 是 子 请 求 ， 则 直接 返回 NGX_OK 表 示 丢 弃 包 体 
成 功 。 


2) 检查 请 求 连接 上 的 读 事件 是 否 在 定时 器 中 ， 这 是 因为 丢弃 包 体 
不 用 考虑 超时 间 题 (linger_timer 例 外 ， 本 章 不 考虑 此 情况 ) 。 如 果 读 
事件 的 timer_set 标 志 位 为 1， 则 从 定时 右 中 移 除 此 事件 。 还 要 检查 
content-length 头 部 ， 如 果 它 的 值 小 于 或 等 于 0， 同 样 意味 着 可 以 直接 返 
加 NGX_OK， 表 示 成 功 丢 弃 了 全 部 包 体 。 或 者 检查 ngx_http_request_t 结 
构 体 的 request_body 成 员 ， 如 果 它 已 经 被 赋值 过 旦 不 再 为 NULL 空 指 
针 ， 则 说 明 已 经 接收 过 包 体 了 ， 这 时 也 需要 返回 NGX_OK 表 示 成 功 。 


是否 痰 巧 已 经 接收 到 完整 的 包 体 (如 果 包 体 很 小 ， 那 么 这 是 非常 可 能 
发 生 的 事 ) ， 如 果 已 经 接收 到 完整 的 包 体 ， 则 跳 到 第 1 步 直接 返回 
NGX_OK， 表 示 丢 弃 包 体 成 功 ， 否 则 ， 说 明 需 要 多 次 的 调度 才能 完成 


丢弃 包 体 这 一 动作 ， 此 时 把 请 求 的 read_event_handler 成 员 设 置 为 
ngx_http_discarded_request_body_handler 方 法 。 


[检查 当前 请 求 是 否 可 以 放弃 包 体 ] 


[检查 连接 上 的 读 事件 是 否 在 定时 器 中 ] 
[当前 请 求 不 是 原始 请 求 , 或 者 包 体 已 经 丢弃 ] 


[ 读 事 件 在 定时 器 中 ] 


[ 读 事 件 不 在 定时 器 中 ] 2 ) 将 读 事件 从 


定时 器 中 移 除 
[检查 content-length 头 部 ] 


[content_length 小 于 或 等 于 0, 或 者 已 经 接收 过 包 体 ] 
[检查 header_in 组 冲 区 ] 
[在 headerin 缓 冲 区 里 接收 到 完整 的 包 体 ] 


[header_ in 缓冲 区 中 未 接收 到 完整 包 体 ] 


3) 设置 后 续 接 收 连接 上 


TCP 流 的 read_event_handler 方 法 1) 返回 NGX_OK 


4) 将 读 事件 
添加 到 epoll 中 


5 ) 调用 ngx_http_read_discarded_request_body 
接收 包 体 并 丢弃 
[检查 方法 的 返回 值 ] 


[返回 NGX_OK] 


[返回 非 NGX_OK] 


6 ) count 引 用 计数 加 1 
并 返回 NGX_OK 


7) 设置 延迟 关闭 标志 位 为 0 
并 返回 NGX _OK 


图 11-16 ngx_http_discard_request_body 方 法 的 流程 图 
4) 调用 ngx_handle_read_event 方 法 把 读 事件 添加 到 epoll 中 。 


5) 调用 ngx_http_read_discarded_request_body 方 法 接收 包 体 ， 检 测 
它 的 返回 值 。 如 果 返 回 NGX_OK， 则 跳 到 第 7 步 ， 否 则 跳 到 第 6 步 。 


6) 返回 非 NGX_OK 表 示 Nginx 的 事件 框架 触发 事件 需要 多 次 调度 
才能 完成 丢弃 包 体 这 一 动作 ， 于 是 先 把 引用 计数 加 1， 防 止 这 边 还 在 丢 
弃 包 体 ， 而 其 他 事件 却 已 让 请 求 意 外 销毁 ， 引 发 严重 错误 。 同 时 把 
ngX_http_request_t 结 构 体 的 discard_body 标 志 位 置 为 1， 表 示 正 在 丢弃 包 
体 ， 并 返回 NGX_OK， 当 然 ， 这 时 的 NGX_OK 绝 不 表示 已 经 成 功 地 接 
收 完 包 体 ， 只 是 说 明 ngx_http_discard_request_body 执 行 完毕 而 已 。 


7) 返回 NGX_OK 表 示 已 经 接收 到 完整 的 包 体 了 ， 这 时 将 请 求 的 
lingering_close 延 时 关闭 标志 位 设 为 0， 表 示 不 需要 为 了 包 体 的 接收 而 延 
时 关闭 了 ， 同 时 返回 NGX_OK 表 示 丢 弃 包 体 成 功 。 


从 以 上 步骤 可 以 看 出 ， 当 ngx_http_discard_request_body 方 法 返回 
NGX_OK 时 ， 是 可 能 表达 很 多 意思 的 。HTTP 框 架 的 目的 是 希望 各 个 
HTTP 模 块 不 要 去 关心 丢弃 包 体 的 执行 情况 ， 这 些 工 作 完 全 由 HTTP 框 


网 


下 面 再 看 看 在 第 5 步调 用 的 ngx_http_read_discarded_request_body 方 
法 的 执行 流程 ， 如 图 11-17 所 示 。 


[检查 还 需要 接收 的 包 体 长 度 headers_in.content_length_n] 


[丢弃 的 包 体 长 度 已 经 达到 content-length 指 定 长 度 ] 


SP 


[还 有 包 体 需要 处 理 ] 1) 设置 后 续 接 收 连接 上 TCP 流 的 
read_event handle 访 法 


[ 套 接 字 缓 冲 区 上 没有 可 读 内 容 ] 


[ 套 接 字 上 有 可 读 TCP 流 ] 


3) 由 TCP 连 接 的 套 接 字 缓冲 区 


中 读 取 请 求 的 包 体 
[检查 recv 接 收 方法 的 返回 值 ] 
[ 套 接 字 缓 冲 区 已 空 ， 
CS 需要 继续 读 取 包 体 ] 2) 返回 
NGX _AGAIN 
[客户 端 关闭 了 连接 ] 
4) 返回 
NGX OK 


5) 更 新 已 经 丢弃 


的 包 体 长 度 


\ 


图 11-17 ngx_http_read_discarded_request_body 方 法 的 流程 图 


可 以 看 到 ， 虽 然 ngx_http_read_discarded_request_body 方 法 与 
ngx_http_do_read_client_ request body 方法 很 类 似 ， 但 前 者 比 后 者 简单 多 
了 ， 毕 竞 不 需要 保存 接收 到 的 包 体 。 下 面 简单 分 析 一 下 图 11-17 中 的 5 个 


步骤 。 


1) 丢弃 包 体 时 请 求 的 request_body 成 员 实际 上 是 NULL 空 指针 ， 那 
么 用 什么 变量 来 表示 已 经 丢弃 的 包 体 有 多 大 呢 ? 实际 上 这 时 使 用 了 请 
求 ngx_http_request_t 结 构 体 headers_in 成 员 里 的 content_length_n， 最 初 
它 等 于 content-length 头 部 ， 而 每 丢弃 一 部 分 包 体 ， 就 会 在 
content_length_n 变 量 中 减 去 相应 的 大 小 。 因 此 ，content_length_n 表 示 还 
需要 丢弃 的 包 体 长 度 ， 这 里 首先 检查 请 求 的 content_length_n 成 员 ， 如 
有 果 它 已 经 等 于 0， 则 表示 已 经 接收 到 完整 的 包 体 ， 这 时 要 把 
read_event_handler 重 置 为 ngx_http_block_reading 方 法 ， 表 示 如 果 再 有 可 
读 事件 被 触发 时 ， 不 做 任何 处 理 。 同 时 返回 NGX_OK， 告 诉 上 层 的 方 
法 已 经 丢弃 了 所 有 人 包 体 。 


2) 如 果 连 接 套 接 字 的 缓冲 区 上 没有 可 读 内 容 ， 则 直接 返回 
NGX_AGAIN， 告 诉 上 层 方法 需要 等 待 读 事件 的 触发 ， 等 待 Nginx 框 架 
的 再 次 调度 。 


3) 调用 recv 方 法 读 取 包 体 。 根 据 返 回 值 确定 ， 如 果 套 接 字 缓冲 区 
中 没有 读 取 到 内 容 ， 而 需要 继续 读 取 则 跳 到 第 2 步 ， 如 果 客 户 端 主动 关 
财 了 连接 ， 则 跳 到 第 4 步 ， 如 采 读 取 到 了 内 容 ， 则 跳 到 第 5 步 。 


4) 既然 客户 端 主动 关闭 了 连接 ， 直 接 返回 NGX_OK 告 诉 上 层 方法 
结束 丢弃 包 体 动作 即 可 。 


5) 接收 到 包 体 后 ， 要 更 新 请 求 的 content_length_n 成 员 (参见 第 1 
步 中 的 描述 ) ， 同 时 再 跳 回 到 第 1 步 准备 再 次 接收 包 体 。 


最 后 再 看 看 请 求 的 ngx_handle_read_event 指 定 的 
ngX_http_discarded_request_body_handler 方 法 ， 在 新 的 可 读 事件 被 触发 
时 ，HTTP 框 架 将 会 调用 它 来 处 理事 件 ， 图 11-18 给 出 了 该 方法 的 流程 。 


[检查 连接 上 的 读 事件 是 否 超时 ] 
[已 经 接收 请 求 超时 ] 


1 ) 调 用 ngx_http_finalize _request 


方法 结束 请 求 


[接收 请 求 未 超时 ] 


2) 调用 ngx_http_read_discarded_request 1 yody 
方法 接收 包 体 
[检查 方法 的 返回 值 
[返回 值 是 NGX OK| 


3) 调用 ngx_http 
方法 结 


finalize _request 


束 请 求 ， 参 数 为 NCX_DONE 


4 ) 将 读 事件 添加 到 epoll 中 


图 11-18 ngx_http_discarded_request_body_handler 方 法 的 流程 图 


实际 上 ，ngx_http_discarded_request_body_handler 方 法 还 涉及 
lingering_time 的 处 理 ， 为 了 减少 非 主干 内 容 的 篇 幅 ， 本 章 将 不 涉及 此 
内 容 ， 因 此 图 11-18 中 也 没有 给 出 。 下 面 分 析 一 下 图 11-18 中 的 4 个 步 


1) 首先 检查 TCP 连 接 上 的 读 事 件 的 timedout 标 志 位 ， 为 1 时 表示 已 
经 超时 ， 这 时 调用 ngx_http_finalize_request 方 法 结束 请 求 ， 传 递 的 参数 


是 NGX ERROR， 流 程 结 束 。 


2) 调用 ngx_http_read_discarded_request_body 方 法 接收 包 体 ， 检 测 
其 返回 值 。 如 果 返 回 NGX_OK， 则 跳 到 第 3 步 执 行 ， 否 则 跳 到 第 4 步 。 


3) 此 时 表示 已 经 成 功 地 丢弃 完 所 有 的 包 体 ， 这 一 步骤 将 请 求 的 正 
在 丢弃 包 体 discard_body 标 志 位 置 为 0， 将 延迟 关闭 标志 位 
lingering_close 也 置 为 0， 再 调用 ngx_http_finalize_request 方 法 结束 请 求 
注意 ， 它 的 第 2 个 参数 是 NGX_DONE ，11.10.6 节 将 会 介绍 NGX_DONE 
参数 引发 的 动作 。 然 后 流程 结束 。 


4) 仍然 需要 调用 ngx_handle_read_event 方 法 把 读 事件 添加 到 epoll 
中 ， 期 竺 新 的 可 读 事件 到 来 。 


以 上 介绍 了 丢弃 包 体 的 全 部 流程 ， 可 以 看 到 ， 这 个 简单 的 动作 其 
实 也 需要 很 多 步 又 才能 完成 ， 但 它 非 常 高 效 ， 没 有 任何 阻塞 进程 ， 也 
没有 让 进程 休眠 的 操作 。 同 时 ， 对 于 HTTP 模块 而 言 ， 它 使 用 起 来 也 比 
较 简单 ， 值 得 读 着 学 习 。 


11.9 ”发 送 HITTP 啊 应 


本 世 开 始 讨论 第 3 章 中 已 出 现 过 的 发 送 HITP 啊 应 的 两 个 方法 : 
ngx_http_send_header 方 法 和 ngx_http_output_filter 方 法 。 这 两 个 方法 将 
负责 把 HTTP 响 应 中 的 应 答 行 、 头 部 、 包 体 发 送 给 客户 端 。Nginx 是 一 
个 全 异步 的 事件 驱动 染 构 ， 那 么 仅仅 调用 ngx_http_send_header 方 法 和 
ngx_http_output_filter 方 法 ， 残 可 以 把 响应 全 部 发 送 给 客户 端 吗 ? 当然 
不 是 ， 当 响应 过 大 无 法 一 次 发 送 完 时 (TCP 的 滑动 窗口 也 是 有 限 的 ， 一 
次 非 阻塞 的 发 送 多 半 是 无 法 发 送 完整 的 HITP 啊 应 的 ) ， 束 需要 向 epoll 
以 及 定时 句 中 添加 写 事件 了 ， 当 连接 再 次 可 写 时 ， 就 调用 
ngx_http_writer 方 法 继续 发 送 啊 应 ， 直 到 全 部 的 响应 都 发 送 到 客户 端 为 
从 


以 上 大 致 说 了 一 下 HTTP 框 染 为 发 送 啊 应 所 要 做 的 工作 ， 然 而 ， 对 
于 各 个 HTTP 模 块 而 言 ， 绝 大 多 数 情 况 下 发 送 HTTP 啊 应 时 就 古 这 个 请 
求 结束 的 时 候 ， 难 道 说 还 要 像 接收 包 体 那样 ， 传 递 一 个 post_handler 回 
调 方 法 ， 等 所 有 的 啊 应 都 发 送 完 时 再 回调 HTTP 模 块 的 post_handler 方 法 
来 关闭 请 求 吗 ? 这 个 设计 显然 是 不 好 的 ， 根 据 HTTP 的 特点 ， 只 要 开始 
发 送 啊 应 基本 上 可 以 确定 请 求 束 要 结束 了 。 因 此 ，HTTP 采 用 的 设计 
和 是， 使 用 ngx_http_output_filter 方 法 发 送 啊 应 时 ， 必 须 与 结束 请 求 的 


ngx_http_finalize_request 方 法 配合 使 用 (ngx_http_finalize_request 方 法 会 


把 请 求 的 write_event_handler 设 置 为 ngx_http_writer 方 法 ， 并 将 写 事件 应 
加 到 epoll 和 定时 器 中 ) ， 这 样 束 使 得 真正 负责 在 后 人 台 异 步 地 发 送 响 应 
的 ngx_http_writer 方 法 对 HTTP 模 块 而 言 也 是 透明 的 。 


11.9.1 节 中 将 介绍 发 送 HTTP 员 应 行 、 头 部 的 ngx_http_send_header 
方法 ，11.9.2 市 将 介绍 发 送 啊 应 包 体 的 ngx_http_output_filter 方 法 ， 同 时 
在 这 两 节 中 还 会 穿插 介绍 如 何 配 合 ngx_http_finalize_request 方 法 使 用 ， 
实现 异步 的 发 送 机 制 。 最 后 在 11.9.3 节 会 介绍 在 后 台 发 送 啊 应 的 


ngx_http_writer 方 法 。 


11.9.1 ngx_http_send_header 


ngx_http_send_header 方 法 负 员 构造 HTTP 了 响应 行 、 尖 部 ， 同 时 会 把 
它们 发 送 给 客户 端 。 发 送 响应 头 部 使 用 了 第 6 章 所 述 的 流水 线 式 的 过 滤 
模块 思想 ， 即 通过 提供 统一 的 接口 ， 让 各 个 感 兴 趣 的 HTTP 模 块 加 入 到 
ngx_http_send_header 方 法 中 ， 然 后 通过 每 个 过 滤 模 块 C 源 文件 中 独 有 的 
ngx_http_next_header_ filter 指针 将 各 个 过 滤 头 部 的 方法 连接 起 来 ， 这 
样 ， 在 调用 ngx_http_send_header 方 法 时 ， 实 际 束 是 依次 调用 了 所 有 头 
部 过 滤 模 块 的 方法 ， 其 中 ， 链 表 里 的 最 后 一 个 头 部 过 滤 方 法 将 负责 发 
送 头 部 。 因 此 ， 这 些 过 滤 模 块 组 成 的 链表 顺序 是 非常 重要 的 ， 我 们 在 


第 6 章 的 6.2.1 节 和 6.2.2 节 已 经 介绍 过 这 部 分 内 容 ， 这 里 不 再 长 述 。 


调用 ngx_http_send_header 方 法 时 ， 最 后 一 个 头 部 过 滤 模 块 叫做 
ngx_http_header_filter_module 模 块 ， 之 前 的 头 部 过 滤 模 块 会 根据 特性 去 
修改 表示 请 求 的 ngx_http_request_t 结 构 体 中 headers_out 成 员 里 的 内 容 ， 
而 最 后 一 个 头 部 过 滤 模 块 ngx_http_header_filter_ module 提 供 的 
ngx_http_header filter 方 法 则 会 根据 HTTP 规 则 把 headers_out 中 的 成 员 变 
量 序 列 化 为 字符 流 ， 并 发 送出 去 ， 而 本 市 的 重点 就 在 于 说 明 
ngx_http_header filter 方 法 所 做 的 工作 。 


在 了 解 ngx_http_header _filter 方 法 之 前 ， 我 们 还 是 得 先 回 顾 一 下 事 
件 张 动机 制 ， 因 为 它 要 求 任 何 操作 都 不 可 以 阻塞 进程 ， 
ngX_http_header filter 方 法 当然 也 不 能 例外 。 那 么 ， 如 果 要 发 送 的 啊 应 
头 部 大 于 套 接 字 可 写 的 缓存 ， 无 法 一 次 把 响应 头 部 发 送出 去 怎么 办 ? 
这 束 需 要 使 用 ngx_http_request_t 结 构 体 中 ngx_chain_t 类 型 的 成 员 out 
了 ， 它 将 会 保存 没有 发 送 完 的 〈 剩 余 的 ) 响应 头 部 。 那 么 ， 什 么 时 候 
发 送 请 求 out 成 员 中 保存 的 剩余 响应 头 部 呢 ? 这 就 要 结合 用 于 结束 请 求 
的 ngx_http_finalize_request 方 法 来 说 了 。 


当 ngx_http_header_ filter 方法 无 法 一 次 性 发 送 HTTP 头 部 时 ， 将 会 
以 下 两 个 现象 同时 发 生 。 


请 求 的 out 成 员 中 将 会 保存 剩余 的 啊 应 头 部 。 


‘ngx_http_header filter 方法 返回 NGX_AGAIN 。 


如 果 这 个 啊 应 没有 包 体 ， 那 么 这 时 通常 已 经 可 以 调用 
ngx_http_finalize_request 方 法 来 结束 请 求 了 ， 参 见 11.10.6 方 中 
ngx_http_finalize_request 方 法 的 原型 ， 它 的 第 2 个 参数 很 关键 ， 我 们 需 
要 把 NGX_AGAIN 传 进去 ， 这 样 ngx_http_finalize_request 方 法 就 理解 了 
实际 上 还 需要 HTTP 框 架 继续 发 送 请 求 out 成 员 中 保存 的 剩余 响应 字符 
流 。ngx_http_finalize request 方法 会 设置 请 求 的 write _event_handler 成 员 
为 ngx_http_writer 方 法 ， 这 样 ， 当 连接 上 有 可 写 事件 时 ， 束 会 调用 
11.9.3 廊 摘 述 的 ngx_http_writer 方 法 继续 发 送 和 独 余 的 HTTP 啊 尺 。 下 面 完 
来 看 看 ngx_http_header filter 方 法 的 流程 图 ， 如 图 11-19 所 示 。 


[检查 请 求 的 header_sent 标志 位 ] 


四 
[header_sent 标志 位 为 0 ] [headersent 标志 位 为 1 ] 


2 ) 将 header_sent 


标志 位 置 为 ] 
[检查 当前 请 求 是 于 请 求 还 是 原始 请 求 ] 


[当前 请 求 不 是 原始 请 求 ] 


[当前 请 求 是 原始 请 求 , 再 检查 请 求 的 HTTP 版 本 ] 
[HTTP 版 本 小 于 1.0] 


[HTTP 版 本 为 1.0 或 者 1.1] 


3) 计算 响应 行 、 1) 返 回 
头 部 序列 化 后 字符 流 长 度 NGX_OK 


4) 在 内 存 池上 分 配 用 于 
存放 响应 字符 流 的 缓存 


5) 将 啊 应 行 、 
头 部 按 规 则 序列 化 到 缓存 中 


6) 调用 ngx_http_write _filter 
方法 发 送 构造 好 的 缓存 


® 


图 11-19 ”ngx_http_header filter 方 法 的 流程 图 


下 面 描 述 一 下 图 11-19 中 的 6 个 步骤 。 


1) 首先 检查 请 求 ngx_http_request_t 结 构 体 的 header_sent 标 志 位 ， 
如 果 header_sent 为 1， 则 表示 这 个 请 求 的 响应 头 部 已 经 发 送 过 了 ， 不 需 
要 再 癌 下 执行 ， 直 接 返 回 NGX_OK 即 可 。 


2) 正式 进入 发 送 响 应 头 部 阶段 ， 为 防止 反复 地 发 送 响应 头 部 ， 将 
header_sent 标 志 位 置 为 1。 同 时 需要 检查 当前 请 求 是 否 是 客户 端 发 来 的 
原始 请 求 ， 如 果 当 前 请 求 只 是 一 个 子 请 求 ， 它 是 不 存在 发 送 HTTP 响 应 
头 部 这 个 概念 的 ， 因 此 ， 如 果 当 前 请 求 不 是 main 成 员 指 向 的 原始 请 求 
时 ， 跳 到 第 1 步 直接 返回 NGX_OK。 如果 HTTP 版 本 小 于 1.0， 同 样 不 需 
要 发 送 响应 头 部 ， 仍 然 跳 到 第 1 步 返 回 NGX_OK 。 


3) 根据 请 求 headers_out 结 构 体 中 的 错误 码 、HTTP 头 部 字符 串 ， 计 
算出 如 果 把 响应 头 部 序列 化 为 一 个 字符 串 共 需要 多 少 字 节 。 


4) 在 请 求 的 内 存 池 中 分 配 第 3 步 计 算出 的 缓冲 区 。 
5) 将 响应 行 、 头 部 按照 HTTP 的 规范 序列 化 地 复制 到 缓冲 区 中 。 


6) 将 第 4 步 中 分 配 的 缓冲 区 作为 参数 调用 ngx_http_write_filter 方 
法 ， 将 响应 头 部 发 送出 去 。 


注意 ， 第 6 步 是 通过 调用 ngx_http_write_filter 方 法 来 发 送 响应 头 部 
的 。 事 实 上 ， 这 个 方法 是 包 体 过 滤 模 块 链表 中 的 最 后 一 个 模块 


ngx_http_write_filter_module 的 处 理 方法 ， 当 HTTP 模 块 调用 
ngx_http_output_filter 方 法 发 送 包 体 时 ， 最 终 也 是 通过 该 方法 发 送 啊 应 
的 (在 11.9.2 市 中 将 详细 地 介绍 这 一 方法 ) 。 当 一 次 无 法 发 送 全 部 的 组 
冲 区 内 容 时 ，ngx_http_write_filter 方 法 是 会 返回 NGX_AGAIN 的 (同时 
将 未 发 送 完成 的 缓冲 区 放 到 请 求 的 out 成 员 中 ) ， 也 就 是 说 ， 发 送 响应 
头 部 的 ngx_http_header_ filter 方法 会 返回 NGX_AGAIN。 如 果 不 需 要 再 
发 送 包 体 ， 那 么 这 时 就 需要 调用 ngx_http_finalize_request 方 法 来 结束 请 
求 ， 其 中 第 2 个 参数 务必 要 传递 NGX_AGAIN， 这 样 HTTP 框 架 才 会 继 
续 将 可 写 事件 注册 到 epoll， 并 持续 地 把 请 求 的 out 成 员 中 缓冲 区 里 的 
HTTP 响 应 发 送 完毕 才 会 结束 请 求 。 


11.9.2 ngx_http_output_ filter 


ngx_http_output_filter 方 法 用 于 发 送 啊 应 包 体 ， 它 的 第 2 个 参数 束 是 
用 于 存放 响应 包 体 的 缓冲 区 ， 如 下 所 示 。 


ngx_int_t ngx_http_write_filter(ngx_http_request _t *r, ngx_chain_t *in) 


其 中 第 2 个 参数 in 在 第 6 章 中 已 有 过 详细 的 介绍 ， 这 里 不 再 长 述 。 用 
于 过 小 包 体 的 HTTP 模 块 将 以 ngx_http_next_body_filter 作 为 链表 指针 连 
接 成 一 个 流水 线 ，ngx_http_output_filter 方 法 在 发 送 包 体 时 会 依次 调用 
各 个 过 滤 包 体 方 法 ， 其 中 最 后 一 个 过 滤 包 体 方法 就 是 11.9.1 方 中 介绍 过 


的 ngx_http_write_filter 方 法 ， 它 属于 ngx_http_write_filter_ module 模 块 。 


本 节 与 ngx_http_send_header 方 法 的 介绍 一 样 ， 不 会 讨论 每 个 过 滤 
模块 的 功能 ， 我 们 只 看 最 后 一 个 包 体 过 滤 模 块 是 怎样 发 送 响应 包 体 
的 。 在 图 11-20 中 ，ngx_http_write_filter 方 法 展示 了 HTTP 框 架 是 如 何 开 
始 发 送 HTTP 响 应 包 体 的 。 


图 11-20 中 描述 的 ngx_http_write_filter 方 法 主要 有 13 个 步骤 ， 下 面 详 
细 介 绍 这 些 步 骤 到 确 是 如 何 工 作 的 。 


1) 首先 检查 请 求 的 连接 Fngx_connection_t 结 构 体 的 error 标 志 位 ， 
如 采 error 为 1 表示 请 求 出 错 ， 那 么 直接 返 回 NGX_ERROR。 


2) 找到 请 求 的 ngx_http_request_t 结 构 体 中 存放 的 等 竺 发送 的 缓冲 
区 链表 out， 源 历 这 个 ngx_chain_t 类 型 的 缓冲 区 链表 ， 计 算出 out 绥 促 区 
共 占 用 了 多 大 的 字 廊 数 ， 为 第 9 步 发 送 啊 应 做 准备 。 


人 @@ 注意 “这 个 out 链 表 通 常 都 保存 着 待 发 送 的 响应 。 例 如 ， 在 调 
用 ngx_http_send_header 方 法 时 ， 如 有 末 HTTP 员 应 头 部 过 大 导致 无 法 一 次 
性 发 送 完 ， 那 么 剩余 的 响应 头 部 就 会 在 out 链 表 中 。 


[检查 ngx_connection_ + 结构 体 中 的 error 标 志 位 ] 
[error 标 志 位 为 1] 


[error 标 志 位 为 0] 1 ) 返 回 
2) 遍历 out 缓 冲 区 计算 
到 余 响 应 长 度 
3) 将 本 次 待 发 送 的 缓冲 区 添加 到 
out 尾 部 并 计算 总 长 度 
[检测 现在 的 out 缓 冲 区 是 否 完整 ,是否 有 必要 现在 就 发 送 ] 


[out 不 完整 ， 本 次 可 不 发 送 ] 
[out 组 Ph 区 完整 ] 


4) 取 出 配置 项 sendfile_max_chunk 


并 检查 它 是 和 理 大 于 out 啊 应 长 度 


[检查 写 事 件 delayed 标 志 位 , 以 及 请 求 的 limit_rate 标 志 位 ] 


[limit_rate 不 
[limit_rate 为 0] 
6) 计算 发 送 速 度 是 否 [delayed 为 1， 当 前 不 得 发 送 啊 应 ] 

超过 了 限制 


[目前 发 送 响 应 的 速度 过 快 需 要 减速 
[不 需 站 减速 ] 


7) 写 事 件 的 delayed 
标志 位 置 为 1 


9) 向 客户 端 发 送 缓冲 区 
的 字符 流 
[再 次 检查 limit_rate 标 志 位 ] 
8) 将 写 事件 加 入 
定时 器 


[limit_rate 不 为 0, 需要 限 速 ] 


[limit_rate 为 0] 


10) 再 次 计算 发 送 速度 
是 否 超过 限制 


[不 需要 减速 ] 


5 ) 将 buffer 标 志 位 置 为 可 写 状态 ， 
[发 送 响应 速度 过 快 需要 减速 并 返回 NGX AGAIN 


11) 将 写 事件 添加 到 
定时 器 [还 有 剩余 缓冲 区 待 发 送 ] 


NA 
12) 重 置 out 绥 冲 区 ， 
科 放 已 经 发 送 的 缓存 a 


[发 送 完 毕 ] 


图 11-20 ”ngx_http_write_filter 方 法 的 流程 图 


3) ngx_http_write_filter 方 法 的 第 2 个 参数 in 就 是 本 次 要 发 送 的 缓冲 
区 链表 〈 正 是 由 HTTP 模 块 构造 、 传 递 ) ， 本 步骤 将 类 似 第 2 步 般 历 这 
个 ngx_chain_t 类 型 的 缓存 链表 in， 将 in 中 的 缓冲 区 加 入 到 out 链 表 的 末 
尾 ， 并 计算 out 缓 冲 区 共 占 用 多 大 的 字 节 数 ， 为 第 9 步 发 送 响应 做 准备 。 


在 第 >、 第 3 步 的 遍历 过 程 中 ， 会 检查 缓冲 区 中 每 个 ngx_buf t 块 的 3 
个 标志 位 : flush、recycled、last_buf， 如 果 这 3 个 标志 位 同时 为 0 ( 即 待 
发 送 的 out 链 表 中 没有 一 个 缓冲 区 表示 响应 已 经 结束 或 需要 立刻 发 送出 
去 ) ， 而 且 本 次 要 发 送 的 缓冲 区 in 虽 然 不 为 空 ， 但 以 上 两 步 又 中 计算 出 
的 待 发 送 啊 应 的 大 小 又 小 于 配置 文件 中 的 postpone_output 参 数 ， 那 么 说 
明 当 前 的 缓冲 区 是 不 完整 的 且 没 有 必要 立刻 发 送 ， 于 是 跳 到 第 13 步 直 
接 返 回 NGX_OK 。 


4) 取出 nginx.conf 文 件 中 匹配 请 求 的 sendfile_ max_chunk 配 置 项 
(如 它 属于 某 个 location 块 下 的 配置 项 ) ， 为 第 9 步 计算 发 送 啊 应 的 速度 
做 准备 。 


首先 检查 连接 上 写 事件 的 标志 位 delayed， 如 果 delayed 为 1， 则 表示 
这 一 次 的 epol 调 度 中 请 求 仍 需要 减速 ， 是 不 可 以 发 送 响应 的 ，delayed 
为 1 指明 了 响应 需要 延迟 发 送 ， 这 时 跳 到 第 5 步 执行 ， 如 果 delayed 为 0， 
表示 本 次 不 需要 减速 ， 那 么 再 检查 ngx_http_request_t 结 构 体 中 的 


limit rate 发 送 响应 的 速率 ， 如 果 1limit rate 为 0， 表 示 这 个 请 求 不 需要 限 
制 改 送 速度 ， 直 接 跳 到 第 9 步 执行 ， 如 果 limit_rate 大 于 0， 则 说 明 发 送 
响应 的 速度 不 能 超过 limit_rate 指 定 的 速度 ， 这 时 跳 到 第 6 步 执行 。 


5) 将 客户 端 对 应 的 ngx_connection_t 结 构 体 中 的 buffered 标 志 位 放 
上 NGX_HTTP WRITE _ BUFFERED 宏 ， 同 时 返回 NGX_AGAIN， 这 是 
告诉 HTTP 框 架 out 绥 冲 区 中 还 有 了 啊 应 等 得 发 送 。 


6) ngx_http_request_t 结 构 体 中 的 limit_rate 成 员 表 示 发 送 响应 的 最 
大 速率 ， 当 它 大 于 0 时 ， 表 示 需 要 限 速 ， 首 先 需要 计算 当前 请 求 的 发 送 
速度 是 否 已 经 达到 限 速 条 件 。 


这 里 需要 解释 第 2 章 中 介绍 过 的 nginx.conf 文 件 里 的 两 个 配置 项 : 
limit_rate 和 1limit_rate_after。limit_rate 表 示 每 秒 可 以 发 送 的 字 节 数 ， 超 
文 个 数字 就 需要 限 速 ;然而 ， 限 速 这 个 动作 必须 是 在 发 送 了 
limit_rate_after 字 节 的 响应 后 才能 生效 (对 于 小 响应 包 的 优化 设计 ) 。 
下 面 看 看 这 一 步 是 如 何 使 用 这 两 个 配置 项 来 计算 限 速 的 ， 如 下 所 示 。 


limit = r->limit_ rate * (ngx_ time() - r->start_ sec + 1) 
- (c->sent - clcf->limit_rate after); 


第 9 章 已 介绍 过 ngx_time() 方 法 ， 它 取出 了 当前 时 间 ， 而 start_sec 表 
示 开 始 接收 到 客户 端 请 求 内 容 的 时 间 ，c->sent 表 示 这 条 连接 上 已 经 发 
送 了 的 HTTP 响 应 长 度 ， 这 样 计算 出 的 变量 limit 就 表示 本 次 可 以 发 送 的 


字 节 数 了 。 如 果 limit 小 于 或 等 于 0， 它 表示 这 个 连接 上 的 发 送 响应 速度 
已 经 超出 了 limit_rate 配 置 项 的 限制 ， 所 以 本 次 不 可 以 继续 发 送 ， 跳 到 
第 7 步 执行 ， 如 采 limit 大 于 0， 表 示 本 次 可 以 发 送 limit 字 市 的 响应 ， 那 么 
跳 到 第 9 步 开 始 发 送 啊 应 。 


7) 由 于 达到 发 送 响应 的 速度 上 限 ， 这 时 将 连接 上 写 事件 的 delayed 
标志 位 置 为 1。 


8) 将 写 事 件 加 入 定时 器 中 ， 其 中 超时 时 间 要 根据 第 7 步 算 出 的 
limit 来 计算 ， 如 下 所 示 : 


ngx_add _ timer(c->write，(ngx_msec t) (- limit * 1000 / 『->1Limit_rate + 1)); 


limit 是 已 经 超 发 的 字 节 数 ， 它 是 0 或 者 负数 。 这 个 定时 器 的 超时 时 
间 是 超 发 字 节 数 按照 limit_rate 速 率 算出 需要 等 待 的 时 间 再 加 上 1 毫秒 ， 
它 可 以 使 Nginx 定 时 器 准确 地 在 允许 发 送 响 应 时 激活 请 求 。 之 后 转 到 第 
5 步 执行 。 


9) 本 步 将 把 啊 应 发 送 给 客户 端 。 然 而 ， 缓 冲 区 中 的 响应 可 能 非常 
大 ， 那 么 这 一 次 应 该 发 送 多 少子 市 呢 ? 这 要 根据 第 6 步 计 算出 的 limit 变 
量 ， 以 及 第 4 步 取得 的 配置 项 sendfile_ max_chunk 来 计算 ， 同 时 要 根据 第 
2、 第 3 步 届 有 历 缓冲 区 计算 出 的 竺 发送 字 节 数 来 决定 ， 这 3 个 值 中 的 最 小 
值 即 作为 本 次 发 送 的 啊 应 长 度 。 


发 送 啊 应 后 再 次 检查 请 求 的 limit_rate 标 志 人 位， 如果]imit_rate 为 0， 
则 表示 不 需要 限 速 ， 跳 到 第 12 步 执行 ， 如 果 ]imit_rate 大 于 0， 则 表示 和 需 
要 限 速 ， 跳 到 第 10 步 执行 。 


10) 再 次 按照 第 6 步 中 的 方法 计算 刚 发 送 了 部 分 响应 后 ， 请 求 的 发 
送 速率 是 否 达到 limit_rate 上 限 ， 如 果 不 需 要 减速 就 直接 跳 到 第 12 步 ; 
否则 继续 执行 第 11 步 。 


11) 这 时 表示 第 9 步 发 送 的 响应 速度 还 是 过 快 了 ， 已 经 超 发 了 一 些 
啊 应 ， 那 么 这 里 类 似 第 8 步 ， 计 算出 至 少 要 经 过 多 少 晕 秒 后 才 可 以 继续 
发 送 ， 调 用 ngx_add_timer 方 法 将 写 事件 按照 上 面 计算 出 的 又 秒 作为 超 
时 时 间 深 加 人 a 到 定时 右 中 。 同 时 ， 把 写 事 件 的 delayed 标 志 位 置 为 1。 


12) 重 置 hgx_http_request_t 结 构 体 的 out 绥 冲 区 ， 把 已 经 发 送 成 功 
的 缓冲 区 归还 给 内 存 池 。 如 采 out 链 表 中 还 有 剩余 的 没有 发 送出 去 的 缓 
冲 区 ， 则 添加 到 out 链 表 头 部 ， 跳 到 第 5 步 执行 ， 如 果 已 经 将 out 链 表 中 
的 所 有 缓冲 区 都 发 送 给 客户 端 了 ， 则 执行 第 13 步 。 


13) 返回 NGX_OK 表 示 成 功 。 


以 上 较为 详尽 地 描述 了 负责 实际 发 送 啊 应 的 ngx_http_write_filter 方 
法 是 怎样 工作 的 ， 包 括 如 何 更 新 请 求 里 的 out 绥 冲 区 ， 如 何 根据 限 速 条 
件 以 及 配置 文件 中 的 sendfile_max_chunk 参 数 决定 一 次 可 以 发 送 多 少 字 
节 的 响应 。 


ngx_http_send_header 方 法 最 终 会 调用 ngx_http_write_filter 方 法 来 发 
送 响应 头 部 ， 而 ngx_http_output_filter 方 法 最 终 也 是 调用 
ngx_http_write_filter 方 法 来 发 送 响应 包 体 的 ， 同 样 ， 
ngx_http_output_filter 也 有 可 能 得 到 返回 值 NGX_AGAIN (图 11-20 的 第 5 
步 ) ， 它 表示 还 有 未 发 送 的 响应 缓冲 区 在 out 成 员 中 。 这 时 ， 需 要 以 
NGX_AGAIN 作 为 参数 调用 ngx_http_finalize_request 方 法 ， 该 方法 将 把 
写 事件 的 回调 方法 设 为 ngx_http_writer 方 法 ， 并 由 它 来 把 剩 下 的 响应 全 
部 发 送 给 客户 端 。 


11.9.3 ngx_http_writer 


本 节 介 绍 的 ngx_http_writer 方 法 对 各 个 HTTP 模 块 而 言 是 不 可 见 
的 ， 但 实际 上 它 非常 重要 ， 因 为 无 论 是 ngx_http_send_header 还 是 
ngx_http_output_filter 方 法 ， 它 们 在 调用 时 一 般 都 无 法 发 送 全 部 的 响 
应 ， 剩 下 的 响应 内 容 都 得 靠 ngx_http_writer 方 法 来 发 送 。 如 何 把 
ngx_http_writer 方 法 设置 为 请 求 写 事件 的 回调 方法 呢 ? 这 部 分 内 容 将 在 
11.10.6 节 中 介绍 ， 此 处 关注 的 重点 是 ngx_http_writer 方 法 在 后 台 究 竟 做 
了 些 什 么 。 图 11-21 是 ngx_http_writer 方 法 的 流程 图 ， 如 果 这 个 请 求 的 连 
接 上 可 写 事件 被 触发 ， 也 就 是 TCP 的 滑动 窗口 在 告诉 Nginx 进 程 可 以 发 
送 响 应 了 ， 这 时 ngx_http_writer 方 法 就 开始 工作 了 。 


Ht 


[检查 写 事件 的 timedout 标志 位 , 确定 发 送 啊 应 是 否 超时 ] 


[timedout 为 1, 写 事件 超 时 , 再 检查 写 事 件 的 delayed 标志 位 ] 


[timedout 为 0, 写 事件 未 超时 ] 二 
[delayed 为 1, 这 里 的 超时 是 由 请 求 限 速 导致 ] 


[delayed 为 0 请 求 没 有 限 速 , 所 以 这 里 是 真实 的 发 送 响应 超时 ] 


2 ) 置 写 事 件 的 timedout、 


1 ) 结束 请 求 并 返回 


delayed 标志 位 为 0 
[检查 写 事 件 的 ready 标 志 位 ] 


408 啊 应 码 


[ready 为 0] 
= 


[ready 为 1, 连接 上 可 以 发 送 TCP 流 ] 


3 ) 将 写 事件 加 入 定时 器 中 
5 ) 调用 ngx_http_output_filter 
方法 发 送 响 应 


4) 将 写 事件 加 入 到 epoll 
[检查 发 送 响 应 后 的 ngx_http_request+ 结 构 体 状态 ] 


[out 缓 冲 区 中 仍 有 未 发 送 的 啊 应 ] 


[out 缓 冲 区 中 的 响应 全 部 发 送 完毕 ] 


6 ) 重 置 write _event_handler 方 法 


7) 调用 ngx_http_finalize _request 


方法 结束 请 求 


\ 


图 11-21 ngx_http_writer 方 法 的 流程 图 


下 面 将 详细 介绍 图 11-21 中 的 7 个 步 又 。 


1) 首先 检查 连接 上 写 事件 的 tmedout 标 志 位 ， 如 果 timedout 为 0， 
则 表示 写 事件 未 超时 ， 跳 到 第 5 步 执 行 ， 如 果 timedout 为 1， 则 表示 当前 
的 写 事件 已 经 超时 ， 这 时 有 两 种 可 能 性 ， 第 一 种 ， 由 于 网 络 异常 或 者 
客户 端 长 时 间 不 接收 响应 ， 导 致 真实 的 发 送 响 应 超时 ; 第 二 种 ， 由 于 
上 一 次 发 送 响应 时 发 送 速率 过 快 ， 超 过 了 请 求 的 limit_rate 速 率 上 限 ， 
而 上 市 的 ngx_http_write_filter 方 法 就 会 设置 一 个 超时 时 间 将 写 事件 添 加 
到 定时 器 中 ， 这 时 本 次 的 超时 只 是 由 限 速 导 致 ， 并 非 真 正 超 时 (结合 
图 11-20 理 解 ) 。 那 么 ， 如 何 判断 这 个 超时 是 真 的 超时 还 是 出 于 限 速 的 
考虑 呢 ? 这 要 看 事件 的 delayed 标 志 位 。 从 图 11-20 中 可 以 看 出 ， 如 有 果 坪 
限 速 把 写 事 件 加 入 定时 器 ， 一 定 会 把 delayed 标 志 位 置 为 1， 如 其 中 的 第 
7 步 和 第 11 步 。 如 果 写 事件 的 delayed 标 志 位 为 0， 那 就 是 真 的 超时 了 ， 
这 时 调用 ngx_http_finalize_request 方 法 结束 请 求 ， 传 入 的 参数 是 
NGX_HTTP_REQUEST_TIME_OUT， 表 示 需 要 向 客户 端 发 送 408 错 误 
码 ; 如 果 delayed 标 志 位 为 1， 则 继续 执行 第 2 步 。 


2) 既然 当前 事件 的 超时 是 由 限 速 引起 的 ， 那 么 此 时 可 以 把 写 事件 
的 timedout 标 志 位 和 delayed 标 志 位 都 重 置 为 0。 


再 检查 写 事件 的 ready 标 志 位 ， 如 琳 为 1， 则 表示 在 与 客户 端的 TCP 
连接 上 可 以 发 送 数据 ， 跳 到 第 5 步 执 行 ， 如 果 为 0， 则 表示 暂 不 可 发 送 
数据 ， 跳 到 第 3 步 执行 。 


3) 将 写 事件 添加 到 定时 器 中 ， 这 里 的 超时 时 间 就 是 配置 文件 中 的 
send_timeout 参 数 ， 与 限 速 功能 无 天 。 


4) 调用 ngx_handle_write_event 方 法 将 写 事件 添加 到 epoll 等 事件 收 
集 硕 中 ， 同 时 ngx_http_writer 方 法 结束 。 


5) 调用 ngx_http_output_filter 方 法 发 送 响 应 ， 其 中 第 2 个 参数 (也 
就 是 表示 需要 发 送 的 缓冲 区 ) 为 NULL 指 针 。 这 意味 着 ， 需 要 调用 各 包 
体 过 滤 模 块 处 理 out 缓 冲 区 中 的 剩余 内 容 ， 最 后 调用 ngx_http_write_filter 
方法 把 响应 发 送出 去 。 


发 送 响应 后 ， 查 看 ngx_http_request_t 结 构 体 中 的 buffered 和 
postponed 标 志 位 ， 如 果 任 一 个 不 为 0， 则 意味 着 没有 发 送 完 out 中 的 全 
部 响应 ， 这 时 跳 到 第 3 步 执行 ， 请 求 main 指 针 指 向 请 求 自 身 ， 表 示 这 个 
请 求 是 原始 请 求 ， 再 检查 与 客户 端 间 的 连接 ngx_connection_t 结 构 体 中 
的 buffered 标 志 位 ， 如 采 buffered 不 为 0， 同 样 表示 没有 发 送 完 out 中 的 全 
部 响应 ， 仍 然 跳 到 第 3 步 执行 ， 除 此 以 外 ， 都 表示 out 中 的 全 部 响应 缘 发 
送 完毕 ， 跳 到 第 6 步 执行 。 


6) 将 请 求 的 write_event_handler 方 法 置 为 
ngx_http_request_empty_handler， 也 残 是 说 ， 如 采 这 个 请 求 的 连接 上 再 
有 可 写 事件 ， 将 不 做 任何 处 理 。 


7) 调用 ngx_http_finalize_request 方 法 结束 请 求 ， 其 中 第 2 个 参数 传 
入 的 是 ngx_http_output_filter 方 法 的 返回 值 。 


@@ 注意 ngx_ htp_writer 方 法 仅 用 于 在 后 台 发 送 响应 到 客户 端 。 


11.10 ”结束 HTTP 请 求 


对 于 事件 张 动 鸭 架构 来 说 ， 结 束 请 求 是 一 项 复杂 的 工作 。 因 为 一 
个 请 求 可 能 会 被 许多 个 事件 触发 ， 这 使 得 Nginx 框 架 调 度 到 某 个 请 求 的 
回调 方法 时 ， 在 当前 业务 内 似乎 需要 结束 HTTP 请 求 ， 但 如 果真 的 结束 
了 请 求 ， 销 虹 了 与 请 求 相关 的 内 存 ， 多 半 会 造成 重大 错误 ， 因 为 这 个 
请 求 可 能 还 有 其 他 事件 在 定时 事 或 者 epoll 中 。 当 这 些 事件 被 回调 时 ， 
请 求 却 已 经 不 存在 了 ， 这 束 是 疗 重 的 内 存 访问 越界 错误 ! 如 末 笑 试 在 
属于 某 个 HTTP 模 块 的 回调 方法 中 试图 结束 请 求 ， 先 要 把 这 个 请 求 相关 
的 所 有 事件 (有 些 事件 可 能 属于 其 他 HTTP 模 块 ) 都 从 定时 器 和 epoll 中 
取出 并 调用 其 handler 方 法 ， 这 又 太 复 沫 了 ， 男 外 ， 不 同 HTTP 模 块 上 的 
代码 类 合 太 紧 密 将 会 难以 维护 。 


那 HTTP 框 架 义 是 怎样 解决 这 个 问题 的 呢 ?HTTP 框 架 把 一 个 请 来 
分 为 多 种 动作 ， 如 果 HTTP 框 架 提 供 的 方法 会 导致 Nginx 再 次 调度 到 请 
求 例如， 在 这 个 方法 中 产生 了 新 的 事件 ， 或 者 重新 将 已 有 事件 添加 
到 epoll 或 者 定时 器 中 ) ， 那 么 可 以 认为 这 一 步调 用 是 一 种 独立 的 动 
作 。 例 如 ， 接 收 HTTP 请 求 的 包 体 、 调 用 upstream 机 制 提供 的 方法 访问 
第 三 方 服务 、 派 生出 subrequest 子 请 求 等 。 这 些 所 谓 独 立 的 动作 ， 都 是 
和 告诉 Nginx， 如 于 机 会 合适 束 再 次 调用 它们 处 理 请 求 ， 因 为 这 个 动作 
并 不 是 Nginx 调 用 一 次 它们 的 方法 整 可 以 处 理 完毕 的 。 因 此 ， 每 一 种 动 


作对 于 整个 请 求 来 说 都 是 独立 的 ，HITP 框 架 和 希望 每 个 动作 结束 时 仅 维 
护 目 己 的 业务 ， 不 用 去 关心 这 个 请 求 古 否 还 做 了 其 他 动作 。 这 种 设计 
大 大 降低 了 复杂 度 。 


这 种 设计 具体 又 是 怎么 实现 的 呢 ? 实际 上 ， 在 11.8 世 中 已 经 介绍 
过 ， 每 个 HTTP 请 求 都 有 一 个 引用 计数 ， 每 派生 出 一 种 新 的 会 独立 向 事 
件 收集 器 注册 事件 的 动作 时 (如 ngx_http_read_client_request_body 方 法 
或 者 ngx_http_subrequest 方 法 ) ， 都 会 把 引用 计数 加 1， 这 样 每 个 动作 结 
束 时 都 通过 调用 ngx_http_finalize_request 方 法 来 结束 请 求 ， 而 
ngx_http_finalize_request 方 法 实际 上 却 会 在 引用 计数 减 1 后 先 检 查 引 用 
计数 的 值 ， 如 果 不 为 0 是 不 会 真正 销毁 请 求 的 。 


也 吏 是 说 ，HTTP 框 架 要 求 在 请 求 的 某 个 动作 结束 时 ， 必 须 调 用 
ngx_http_finalize_request 方 法 来 结束 请 求 。ngx_http_finalize_request 方 法 
也 设计 得 比较 复杂 ， 在 第 3 章 中 曾经 谈 到 过 它 最 基本 的 用 法 ， 本 万 中 将 
详细 讨论 ngx_http_finalize_request 方 法 到 底 做 了 些 什么 。 


在 说 明 ngx_http_finalize_request 方 法 前 ， 先 介绍 一 下 HTTP 框 架 提 
供 的 几 个 更 低级 别 的 结束 请 求 方法 。 


11.10.1 ngx_http_close_connection 


ngx_http_close_connection 方 法 是 HITP 框 架 提 供 的 一 个 用 于 释放 
TCP 连 接 的 方法 ， 它 的 目的 很 简单 ， 束 是 关闭 这 个 TCP 连 接 ， 当 且 仅 当 
HTTP 请 求 真正 结束 时 才 会 调用 这 个 方法 。 图 11-22 列 出 了 
ngx_http_close_connection 方 法 所 做 的 工作 。 


1) 将 连接 的 读 / 写 事件 
从 定时 硕 中 取出 


将 过 授 的 访 写 可 作 从 
epol 中 取出 


3) 将 描述 连接 的 ngx_connection_t 
结构 体 释放 到 空闲 连接 池 


4) 关闭 TCP 


5 ) 销毁 连接 ngx_connection_t 


中 的 内 存 池 
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图 11-22 ngx_http_close_connection 方 法 的 流程 图 


下 面 先 来 分 析 一 下 这 个 底层 的 方法 ngx_http_close_connection 究 竟 
做 了 些 什么 。 


1) 首先 将 连接 的 读 / 写 事 件 从 定时 器 中 取出 。 实 际 上 就 是 检查 读 / 
写 事件 的 time_set 标 志 位 ， 如 果 为 1， 则 证 明 事 件 在 定时 器 中 ， 那 么 需 
要 调用 ngx_del_timer 方 法 把 事件 从 定时 如 中 移 除 。 


2) 调用 ngx_del_conn 宏 (或 者 ngx_del_event 宏 ) 将 读 / 写 事件 从 
epoll 中 移 除 。 实 际 上 就 是 调用 第 9 章 重 点 介绍 过 的 ngx_event_actions_t 接 
口中 的 del_conn 方 法 ， 当 事件 模块 是 epoll 模 块 时 ， 就 是 从 epoll 中 移 除 这 
个 连接 的 读 / 写 事件 。 同 时 ， 如 果 这 个 事件 在 ngx_posted_accept_events 
或 者 ngx_posted_events 队 列 中 ， 还 需要 调用 ngx_delete_posted_event 安 把 
事件 从 post 事 件 队列 中 移 除 。 


3) 调用 ngx_free_connection 方 法 把 表示 连接 的 ngx_connection_t 结 
构 体 归还 给 ngx_cycle_t 核 心 结构 体 的 空闲 连接 池 free_connections 。 


4) 调用 系统 提供 的 close 方 法 关闭 这 个 TCP 连 接 套 接 字 。 
5) 销毁 ngx_connection_t 结 构 体 中 的 pool 内 存 池 。 


可 见 ， 这 个 ngx_http_close_connection 方 法 主要 是 针对 连接 做 了 一 
些 工作 ， 它 是 非常 基础 的 方法 。 


11.10.2 ngx_http_free_request 


ngx_http_free_request 方 法 将 会 释放 请 求 对 应 的 ngx_http_request_t 数 
据 结 构 ， 它 并 不 会 像 ngx_http_close_connection 方 法 一 样 去 释放 承载 请 
求 的 TCP 连 接 ， 每 一 个 TCP 连 接 可 以 反复 地 承载 多 个 HTTP 请 求 ， 
此 ，ngx_http_free_request 是 比 ngx_http_close_connection 更 高 层次 的 方 
法 ， 前 者 必然 和 完 于 后 者 调用 。 下 面 看 看 图 11-23 中 ngx_http_free_request 
方法 到 奔 做 了 哪些 工作 。 


在 描述 图 11-23 之 前 ， 先 来 看 一 个 数据 结构 ngx_http_cleanup_t， 它 
的 定义 如 下 。 


和 2) 


1 ) 调用 请 求 cleanup 
链表 内 的 方法 做 清理 工作 


调用 NGX_HTTP_LOG_PHASE 
阶段 的 回调 方法 记录 日 志 


3 ) 销毁 请 求 ngx_htth_request_t 
中 的 内 存 池 


图 11-23 ”ngx_http_free_request 方 法 的 流程 图 


typedef struct ngx_http_cleanup_s ngx_http_cleanup_t; 
struct ngx_http_cleanup_s { 
/ 


/ 由 


HTTP 模 块 提供 的 清理 


资源 的 


回调 方法 


ngx_http_cleanup_pt handler; 
// 希望 给 上 面 的 


handler 方 法 传递 的 参数 


void *data; 


/* 一 个 请 求 可 能 会 有 多 个 


ngx_http_cleanup_t 清 理 方法 ， 这 些 清 理 方 法 间 就 是 通过 


next 指 针 连 接 成 单 链 表 的 


*/ 


}; 


ngx_http_cleanup_t *next,; 


事实 上 ， 任 何 一 个 请 求 的 ngx_http_request_t 结 构 体 中 都 有 一 个 
ngx_http_cleanup_t 类 型 的 成 员 deanup， 如 果 没 有 需要 清理 的 资源 ， 则 
cleanup 为 空 指针 ， 否 则 HTTP 模 块 可 以 向 cleanup 中 以 单 链表 的 形式 无 限 
制 地 添加 ngx_http_cleanup_t 结 构 体 ， 用 以 在 请 求 结束 时 释放 资产。 下 
看 看 handler 方 法 的 定义 ， 如 下 所 示 。 


typedef void (*ngx_http_cleanup_pt)(void *data); 


如 果 需 要 在 请 求 释放 时 执行 一 些 回 调 方法 ， 首 移 需 要 实现 一 个 
ngx_http_cleanup_pt 方 法 。 当 然 ，HTTP 框 架 还 很 友好 地 提供 了 一 个 工 
具 方 法 ngx_http_cleanup_add， 用 于 癌 请 求 中 添加 ngx_http_cleanup_t 结 
构 体 ， 其 定义 如 下 。 


ngx_http_cleanup_t * ngx_http_cleanup_add(ngx_http_request t *r, size t size) 


这 个 方法 返回 的 就 是 已 经 插入 请 求 的 ngx_http_cleanup_t 结 构 体 指 
针 ， 其 中 data 成 员 指 向 的 内 存 都 已 经 分 配 好 ， 内 存 的 大 小 由 Size 参数 指 


站 


上 目 “。 


@@ 半音 事实 上 ， 在 3.8.2 节 中 曾经 简单 地 介绍 过 同样 用 于 清理 
资源 的 ngx_pool_cleanup_t， 它 与 ngx_http_cleanup_pt 是 不 同 的 ， 
ngx_pool_cleanup_t 仅 在 所 用 的 内 存 池 销 毁 时 才 会 被 调用 来 清理 资源 ， 
它 何 时 释放 资源 将 视 所 使 用 的 内 存 池 而 定 ， 而 ngx_http_cleanup_pt 是 在 
ngx_http_request_t 结 构 体 释放 时 被 调用 来 释放 资源 的 。 


下 面 说 明 一 下 ngx_http_free_request 方 法 所 做 的 3 项 主要 工作 。 


1) 循环 地 遍历 请 求 ngx_http_request_t 结 构 体 中 的 deanup 链 表 ， 依 
次 调用 每 一 个 ngx_http_cleanup_pt 方 法 释放 资源 。 


2) 在 11 个 ngx_http_phases 阶 段 中 ， 最 后 一 个 阶段 叫做 
NGX_HTIP_ LOG_PHASE， 它 是 用 来 记录 客户 问 的 访问 日 志 的 。 在 这 
一 步骤 中 ， 将 会 依次 调用 NGX_HTTP_ LOG_PHASE 阶 段 的 所 有 回调 方 
法 记录 日 志 。 官 方 的 ngx_http_log_module 模 块 就 是 在 这 里 记录 access 
log 的 。 


3) 销毁 请 求 ngx_http_request_t 结 构 体 中 的 pool 内 存 池 。 在 销毁 内 
存 池 时 ， 挂 在 该 内 存 池 下 的 由 各 Nginx 模 块 实现 的 ngx_pool_cleanup_t 方 
法 也 会 被 调用 ， 注 意 它 与 第 1 步 的 区 别 。 


人 @@ 注意 ”如果 打开 了 统计 HTTP 请 求 的 功能 ， 
ngx_http_free_request 方 法 还 会 更 新 共享 内 存 中 的 统计 请 求 数 量 的 两 个 


原子 变量 : ngx_stat_reading、ngx_stat_writing， 详 见 14.2.1 字 。 


11.10.3 ngx_http_close_request 


ngx_http_close_request 方 法 是 更 高 层 的 用 于 关闭 请 求 的 方法 ， 当 
然 ，HTTP 模 块 一 般 也 不 会 直接 调用 它 的 。 在 上 面 几 市 中 反复 提 到 的 引 
用 计数 ， 就 是 由 ngx_http_close_request 方 法 负责 检测 的 ， 同 时 它 会 在 引 
用 计数 清 零 时 正式 调用 ngx_http_free_request 方 法 和 
ngx_http_close_connection 方 法 来 释放 请 求 、 关 闭 连 接 。 先 来 看 看 图 11- 
24 中 列 出 的 ngx_http_close_request 方 法 所 做 的 工作 。 


1 ) 对 应 的 原始 请 求 的 
引用 计数 减 1 
[检查 原始 请 求 的 count 引用 计数 仁和 block 标 志 位 ] 


count 等 于 0 日 blocked 为 01 


2 ) 调用 ngx_http_free_ request 方法 


count 大 于 0 或 者 block 大 于 0 | 


3 ) 调用 ngx_http_close_connection 方 法 


图 11-24 ngx_http_close_request 方 法 的 流程 图 


下 面 简 单 说明 一 下 ngx_http_close_request 方 法 所 做 的 工作 。 


1) 首先 ， 由 ngx_http_request_t 结 构 体 的 main 成 员 中 取出 对 应 的 原 
始 请 求 (当然 ， 可 能 就 是 这 个 请 求 本 映 ) ， 再 取出 count 引 用 计数 并 减 
1° 然后 ， 检 查 count 引 用 计数 是 否 已 经 为 0， 以 及 blocked 标 志 位 是 否 为 
0。 如 果 count 已 经 为 0， 则 证 明 请 求 没 有 其 他 动作 要 使 用 了 ， 同 时 
blocked 标 志 位 也 为 0， 表 示 没 有 HTTP 模 块 还 需要 处 理 请 求 ， 所 以 此 时 
请 求 可 以 真正 释放 ， 这 时 跳 到 第 2 步 执 行 ， 如 果 count 引 用 计数 大 于 0， 
或 者 blocked 大 于 0， 这 样 都 不 可 以 结束 请 求 ，ngx_http_close_request 方 
法 直接 结束 。 


2) 调用 ngx_http_free_request 方 法 释放 请 求 。 


3) 调用 ngx_http_close_connection 方 法 关闭 连接 。 


@@ 注意 ”在 官方 发 布 的 HTTP 模 块 中 ，ngx_http_request_t 结 构 体 
中 的 blocked 标 志 位 主要 由 异步 IO 使 用 ，ngx_http_close_request 方 法 正 
征 通过 blocked 配 合 着 异步 IO 工作， 如 条 AIO 上 下 文中 还 在 处 理 这 个 请 
求 ，blocked 必 然 是 大 于 0 的 ， 这 时 ngx_http_close_request 方 法 不 能 结束 
请 求 。 由 于 本 章 不 涉及 异步 AIO， 所 以 略 过 不 提 。 


11.10.4 ngx_http_finalize_connection 


ngx_http_finalize_connection 方 法 虽然 比 ngx_http_close_request 方 法 


高 了 一 个 层次 ， 但 HTTP 模 块 一 般 还 是 不 会 直接 调用 它 。 


ngx_http_finalize_connection 方 法 在 结束 请 求 时 ， 解 决 了 keepalive 特 性 和 
子 请 求 的 问题 ， 几 11-25 中 展示 了 它 所 做 的 工作 。 


下 面 简单 分 析 一 下 ngx_http_finalize_connection 方 法 所 做 的 工作 。 


1) 首先 查看 原始 请 求 的 引用 计数 ， 如 果 不 等 于 1， 则 表示 还 有 多 
个 动作 在 操作 着 请 求 ， 接 着 继续 检查 discard_body 标 志 位 。 如 果 
discard_body 为 0， 则 直接 跳 到 第 3 步 ， 如 果 discard_body 为 1， 则 表示 正 
在 丢弃 包 体 ， 这 时 会 再 一 次 把 请 求 的 read_event_handler 成 员 设 为 
ngX_http_discarded_request_body_handler 方 法 ， 束 如 同 11.8.2 世 中 描述 的 
人 


[检查 原始 请 求 的 count 引 用 计数 ] 


[count 不 等 于 1， 检查 discard_body 标志 位 请 求 是 否 正 丢弃 包 体 | 


[discard_body 为 1] 


1 ) 为 丢弃 包 体 设置 读 
事件 处 理 方法 


[count 为 1, 检查 keepalive 标志 位 ] 


[discard body 为 0] 
将 恋 事 件 添加 到 
十 器 中 


[keepalive 为 0, 检查 是 否 需 要 延迟 关闭 请 求 ] 


[需要 延迟 关闭 请 求 ] 


3 ) 调 用 ngx_http_close_request 


方法 结束 请 求 [keepalive 为 1, 请 求 基 于 keep -alive 连 接 ] 


4) 调 用 ngx_http_set_lingering _close 
方法 延迟 关闭 


5 ) 调 用 ngx_http_set_keepalive 
方法 设置 keepalive 连 接 


图 11-25 ngx_http_finalize_connection 方 法 的 流程 


如 果 引 用 计数 为 1， 则 说 明 这 时 要 真 的 准备 结束 请 求 了 了。 不 过 ， 还 
要 检查 请 求 的 keepalive 成 员 ， 如 果 keepalive 为 1， 则 说 明 这 个 请 求 需 要 


pA 


释放 ， 但 TCP 连 接 还 是 要 复 用 的 ， 这 时 跳 到 第 5 步 执行 ， 如 果 keepalive 
为 0 束 不 需要 考虑 keepalive 请 求 了 了， 但 还 需要 检测 请 求 的 lingering_close 
成 员 ， 如 果 lingering_close 为 1， 则 说 明 需 要 延迟 关闭 请 求 ， 这 时 也 不 能 
真 的 去 结束 请 求 ， 而 是 跳 到 第 4 步 ， 如 有 果 lingering_close 为 0， 才 真 的 跳 
到 第 5 步 结 束 请 求 。 


2) 将 读 事 件 添加 到 定时 右 中 ， 其 中 超时 时 间 是 lingering_timeout 配 
前 项 。 


3) 调用 11.10.3 节 介绍 的 ngx_http_close_request 方 法 结束 请 求 。 


4) 调用 ngx_http_set_lingering_close 方 法 延迟 关闭 请 求 。 实 际 上 ， 
这 个 方法 的 意义 就 在 于 把 一 些 必须 做 的 事情 做 完 (如 接收 用 户 端 发 来 
的 字符 流 ) 再 关闭 连接 。 


5) 调用 ngx_http_set_keepalive 方 法 将 当前 连接 设 为 keepalive 状 态 。 
它 实 际 上 会 把 表示 请 求 的 ngx_http_request_t 结 构 体 释放 ， 却 叉 不 会 调用 
ngx_http_close_connection 方 法 天 闭 连 授 ， 同 时 也 在 检测 keepalive 连 授 是 
否 超时 ， 对 于 这 个 方法 ， 此 处 不 做 详细 解释 。 


11.10.5 ngx_http_terminate_request 


ngx_http_terminate_request 方 法 是 提供 给 HTTP 模块 使 用 的 结束 请 求 
方法 ， 但 它 属于 非 正 常 结束 的 场景 ， 可 以 理解 为 强制 天 闭 请 求 。 也 就 


征 说 ， 当 调用 ngx_http_terminate_request 方 法 结束 请 求 时 ， 它 会 直接 找 
出 该 请 求 的 main 成 员 指 回 的 原始 请 求 ， 并 直接 将 该 原始 请 求 的 引用 计 
数 置 为 1， 同 时 会 调用 ngx_http_close_request 方 法 去 关闭 请 求 。 与 上 文 
不 同 的 是 ， 它 生 HITP 框 架 提 供给 各 个 HITP 人 模块 直 接 使 用 的 方法 ， 篇 
幅 所 限 ， 这 个 方法 束 不 再 详细 介绍 了 。 


11.10.6 ngx_http_finalize_request 


ngx_http_finalize_request 方 法 是 开发 HTTP 模 块 时 最 向 使 用 的 结束 
请 求 方 法 ， 在 第 3 章 中 早已 介绍 过 它 的 简单 用 法 。 事 实 上 ， 
ngx_http_finalize_request 方 法 被 HTTP 框 架设 计 得 极为 复杂 ， 各 种 结束 
请 求 的 场景 都 被 它 考 虑 到 了 ， 下 面 将 详细 讲述 这 个 方法 究竟 做 了 些 什 
么 。 首 先 回 顾 一 下 它 的 定义 。 


void ngx_http_finalize_request(ngx_http_redquest t *r, ngx_int _t rc) 


其 中 ， 参 数 r 束 是 当前 请 求 ， 它 可 能 是 派生 出 的 子 请 求 ， 也 可 能 是 
客户 并 发 来 的 原始 请 求 。 后 面 的 参数 rc 环 非 常 复 杂 了 ， 它 既 可 能 是 
NGX_OK 、 NGX_ERROR 、 NGX_AGAIN 、 NGX_DONE、 
NGX_DECLINED 这 种 系统 定义 的 返回 值 ， 又 可 能 是 类 似 
NGX_HTTP REQUEST _TIME_OUT 这 样 的 HITP 响 应 码 ， 因 此 ， 
ngx_http_finalize_request 方 法 的 流程 异常 复杂 。 学 习 如 何 正确 地 使 用 
ngx_http_finalize_request 方 法 非常 天 键 ， 为 会 涉及 不 同 动作 导致 的 引 


用 计数 增加 、 腊 常情 况 下 目 动 构造 啊 应 、 未 发 送 完 所 有 了 啊 应 时 目 动 癌 
事件 框架 添加 写 事件 回调 方法 ngx_http_writer 等 各 种 场景 。 大 多 数 情况 
下 ， 我 们 都 会 把 其 他 Nginx 方 法 的 返回 值 作为 rc 参数 来 调用 
ngx_http_finalize_request 方 法 ， 但 如 果 要 编写 复杂 的 HTTP 模 块 ， 还 是 
需要 清晰 地 认识 ngx_http_finalize_request 方 法 的 工作 原理 。 


下 面 把 ngx_http_finalize request 方法 的 主要 流程 简化 为 了 17 个 主要 
步 又， 如 网 11-26 所 示 。 


1 ) 检查 第 2 个 


TC 


[re 参数 为 NGX_DECLINED] 


2 坊 设置 write_e event_handler 方 法 为 


[rc 参数 不 是 NGX_DECLINED 和 NGX_DONG， 
检查 是 否 为 原始 请 求 ] 


[属于 subreguest 子 请 求 ] 


[原始 请 求 ] 


4) 调 用 ngx_http finalize_connection 
方法 结束 请 求 


6) 再 次 检查 rc 参数 


[re 参数 为 NGX_ERROR，NGX_HTTP_REQOUEST_TIME_OUT、 
NGX_HTTP_CLIENT_CLOSED_REQOUEST， 或 者 连接 错误 ] 


[re 参数 为 201 或 者 204, 以 及 re 的 值 大 于 或 等 于 300] 


8) 若 为 原 人 定时 器 中 


[re 为 其 他 值 ] 
9 ) 设 置 读 / 事件 的 处 理 方法 为 


ngx_http_requesL_handler 


yD 调用 ngx_http_1 terminate_request 


方法 强制 结束 请 求 
10) 调 用 ngx_http_special_response_handler 


方法 发 送 响应 


_request 


位 查 1 
原始 请 求 
[检查 r 是 否 等 于 r-> main] 


[当前 请 求 不 是 原始 请 求 ] 13) 将 其 交 请 求 漆 帮 到 

)sted_postedrequests 链 表 趾 
[当前 请 求 就 是 原始 请 求 ] A 
[ou 缓冲 区 还 有 剩余 响应 ] 


[ou 级 冲 区 中 的 响应 都 已 发 送 完毕 ] 


Vv 14) 设 置 ngx_http_writer 
人 16) 由 定时 希 中 移 除 为 写 事件 回调 方法 
读 / 写 事件 


15) 将 写 事件 添加 到 定时 器 


17) 调用 ngx_http_finalize_connection 
方法 结束 请 求 


图 11-26 ”ngx_http_finalize_request 方 法 的 流程 图 


下 面 解释 一 下 ngx_http_finalize_request 方 法 所 做 的 工作 。 


1) 首先 检查 rc 参数 。 如 果 rc 为 NGX_DECLINED， 则 跳 到 第 2 步 执 
行 ;， 如 果 rc 为 NGX_DONE， 则 跳 到 第 4 步 执行 ， 除 此 之 外 ， 都 继续 执行 
第 5 步 。 


2) NGX_DECLINED 参 数 表示 请 求 还 需要 按照 11 个 HTTP 阶段 继续 
处 理 下 去 ， 参 考 11.6 广 的 内 容 可 以 知道 ， 这 时 需要 继续 调用 
ngx_http_core_run_phases 方 法 处 理 请 求 。 这 一 步 中 首先 会 把 
ngx_http_request_t 结 构 体 的 write_event_handler 设 为 
ngx_http_core_run_phases 方 法 。 同 上 时， 将 请 求 的 content_handler 成 员 置 
为 NULL 空 指针 ，11.6 市 已 介绍 过 这 个 成 员 ， 它 是 一 种 用 于 在 
NGX_HTTP_CONTENT_PHASE 阶 段 处 理 请 求 的 方式 ， 将 其 设置 为 
NULL 是 为 了 让 ngx_http_core_content_phase 方 法 (11.6.4 节 介绍 ) 可 以 
继续 调用 NGX_HTTP_CONTENT_PHASE 阶 段 的 其 他 处 理 方 法 。 


3) 调用 ngx_http_core_run_phases 方 法 继续 处 理 请 求 ， 


ngx_http_finalize_request 方 法 结 


4) NGX_DONE 人 参数 表示 不 需要 做 任何 事 ， 直 接 调 用 
ngx_http_finalize_connection 方 法 ， 之 后 ngx_http_finalize_request 方 法 结 
束 。 当 某 一 种 动作 (如 接收 HTTP 请 求 包 体 ) 正常 结束 而 请 求 还 有 业务 
要 继续 处 理 时 ， 多 半 都 是 传递 NGX_DONE 参 数 。 由 11.10.4 节 我 们 知 


道 ， 这 个 ngx_http_finalize_connection 方 法 还 会 去 检查 引用 计数 情况 ， 
并 不 一 定 会 销毁 请 求 。 


5) 检查 当前 请 求 是 否 为 subrequest 子 请 求 ， 如 果 不 是 ， 则 跳 到 第 6 
步 执行 ， 如 果 是 子 请 求 ， 那 么 调用 post_subrequest 下 的 handler 回 调 方 
去 。 在 第 6 章 中 曾经 介绍 过 subrequest 的 用 法 ， 可 以 看 到 post_subrequest 
正 是 此 时 被 调用 的 。 


6) 第 1 步 只 是 把 rc 参数 的 两 种 特殊 值 处 理 掉 了 ， 现 在 又 需要 再 次 检 
查 rc 参 数 了 。 如 有 果 rc 值 为 NGX_ERROR、 
NGX_HTTP_ REQUEST TIME OUT、 NGX_HTTP_CLOSE、 
NGX_HTTP_CLIENT_CLOSED_REQUEST， 或 者 这 个 连接 的 error 标 志 
为 1， 那 么 路 到 第 7 步 执行 ， 如 采 rc 为 NGX_HTTP_CREAIED、 
NGX_HTTP_ NO_CONTENT 或 者 大 于 或 等 于 
NGX_HTTP_SPECIAL_RESPONSE， 则 表示 请 求 的 动作 是 上 传 文件 ， 
或 者 HTTP 模 块 需要 HTTP 框 染 构 造 并 发 送 响 应 码 大 于 或 等 于 300 以 上 的 
特殊 响应 ， 这 时 跳 到 第 8 步 执行 ， 其 他 情况 下 ， 直 接 跳 到 第 12 步 执行 。 


7) 这 一 步 直接 调用 ngx_http_terminate_request 方 法 强制 结束 请 求 ， 
同时 ，ngx_http_finalize_request 方 法 结束 。 


8) 检查 当前 请 求 的 main 是 否 指向 自己 ， 如 果 是 ， 这 个 请 求 就 是 来 
目 客户 端的 原始 请 求 〈 非 子 请 求 ) ， 这 时 检查 读 / 写 事件 的 timer_set 标 


志 位 ， 如 果 timer_set 为 1， 则 表明 事件 在 定时 器 中 ， 需 要 调用 
ngx_del_timer 方 法 把 读 / 写 事件 从 定时 郁 中 移 除 。 


9) 设置 读 / 写 事件 的 回调 方法 为 ngx_http_request_handler 方 法 ， 这 
个 方法 在 11.6 节 中 介绍 过 ， 它 会 继续 处 理 HTTP 请 求 。 


10) 调用 ngx_http_special_response_handler 方 法 ， 该 方法 负责 根据 
rc 参数 构造 完整 的 HTTP 了 响应 。 为 什么 可 以 在 这 一 步 中 构造 这 样 的 响应 
呢 ? 回顾 一 下 第 7 步 ， 这 时 rc 要 么 是 表示 上 传 成 功 的 201 或 者 204， 要 人 么 
就 是 表示 异步 的 300 以 上 的 响应 码 ， 对 于 这 些 情 况 ， 都 是 可 以 让 HTTP 
框架 独立 构造 响应 包 的 。 


11) 再 次 调用 ngx_http_finalize_request 方 法 结束 请 求 ， 不 过 这 时 的 
rc 参数 实际 上 是 第 10 步 ngx_http_special_response_handler 方 法 的 返回 
值 。 


12) 再 次 检查 请 求 的 main 成 员 是 否 指向 自己 ， 即 当前 请 求 是 否 为 
原始 请 求 。 如 果 不 是 客户 端 发 来 的 原始 请 求 ， 跳 到 13 步 继续 执行 ， 如 
果 是 原始 请 求 ， 那 么 还 需要 检查 out 缓 冲 区 内 是 否 还 有 没 发 送 完 的 响 
应 ， 如 果 有 ， 则 跳 到 第 14 步 继续 执行 ， 如 果 没 有 ， 则 可 以 结束 请 求 
了 ， 此 时 跳 到 第 16 步 。 


13) 由 于 当前 请 求 是 子 请 求 ， 那 么 正常 情况 下 需要 跳 到 它 的 父 请 
求 上 ， 激 活 父 请 求 继续 向 下 执行 ， 所 以 这 一 步 首先 根据 


ngx_http_request_t 结 构 体 的 parent 成 员 找 到 父 请 求 ， 再 构造 一 个 
ngx_http_posted_request_t 结 构 体 把 父 请 求 放 置 其 中 ， 最 后 把 该 结构 体 添 
加 到 原始 请 求 的 posted_requests 链 表 中 ， 这 样 11.7 廊 中 介绍 过 的 
ngx_http_run_posted_requests 方 法 就 会 在 图 11-12 描 述 的 流程 中 调用 父 请 
求 的 write_event_handler 方 法 了 。 


14) 在 11.9 节 中 多 次 讲 到 ， 当 HTTP 响 应 过 大 ， 无 法 一 次 性 发 送 给 
客户 端 时 ， 需 要 调用 ngx_http_finalize_request 方 法 结束 请 求 ， 而 该 方法 
会 把 11.9.3 节 介绍 的 ngx_http_writer 方 法 注册 给 epoll 和 定时 絮 ， 当 连接 
再 次 可 写 时 就 会 继续 发 送 镜 余 的 响应 ， 这 些 工作 就 是 在 第 14、 第 15 步 
中 完成 的 。 这 一 步 先 把 请 求 的 write_event_handler 成 员 设 为 


ngx_http_writer 方 法 0 


15) 如 果 写 事件 的 delayed 标 志 位 为 0， 就 把 写 事件 添加 到 定时 器 
中 ， 超 时 时 间 就 是 nginx.conf 文 件 中 的 send_timeout 配 置 项 ， 当 然 ， 如 果 
delayed 为 1， 则 表示 限制 发 送 速 度 ， 从 11.9.2 市 可 以 看 出 ， 在 需要 限 速 
时 ， 根 据 计算 得 到 的 超时 时 间 已 经 把 写 事件 添加 到 定时 器 中 了 “。 再 调 
用 ngx_handle_write_event 方 法 把 写 事件 添加 到 epoll 中 。 


16) 到 了 这 里 真 的 要 结束 请 求 了 。 首 先 判 断 读 / 写 事 件 的 timer_set 
标志 位 ， 如 果 timer_set 为 1， 则 需要 把 相应 的 读 / 写 事件 从 定时 器 中 移 


除 。 


17) 调用 11.10.4 节 中 介绍 过 的 ngx_http_finalize_connection 方 法 结 
束 请 求 。 


事实 上 ，ngx_http_finalize_request 方 法 的 分 支流 程 远 不 止 上 面 的 17 
步 ， 为 了 让 读者 清晰 地 理解 其 主要 工作 ， 许 多 不 太 重 要 的 分 文 都 从 图 
10-26 中 去 除了 。 到 此 ， 读 考 应 当 对 ngx_http_finalize_request 方 法 有 了 相 
当 全 面 的 了 解 ， 这 时 再 开发 HTTP 模 块 就 可 以 灵活 地 指定 rc 参数 了 。 


11.11 - 相 续 


本 章 系 统 地 介绍 了 HTTP 框 架 是 如 何 运行 的 ， 特 别 是 它 如 何 与 第 9 

章 介 绍 的 事件 框架 交互 ， 以 及 如 何 与 本 书 第 二 部 分 介绍 的 普通 HTTP 模 
块 交 互 。 阅 读 完 本 章 内 容 后 ， 相 信 读 者 会 对 HTTP 模 块 的 开发 有 一 个 全 
新 的 认识 ， 甚 至 对 于 在 HTTP 请 求 的 处 理 过 程 中 HTTP 模 块 占 用 的 服务 

器 资源 都 会 有 深入 的 了 解 ， 也 就 是 说 ， 这 时 读者 应 当 具 备 开 发 复杂 的 

HTTP 模 块 的 能 力 了 ， 甚 至 可 以 处 理 非 HTTP， 而 是 其 他 基于 TCP 的 应 

用 层 协议 ， 它 们 也 可 以 仿照 HTTP 框 架 ， 定 义 一 种 新 的 模块 类 型 和 处 理 
框架 ， 从 而 高 效 地 处 理 新 业务 。 


upstream 机 制 实际 上 也 属于 HTTP 框 架 的 内 容 ， 下 一 划 中 我 们 将 介 
绍 它 的 实现 原理 。 


第 12 章 upstream 机 制 的 设计 与 实现 


第 5 章 中 曾经 举例 说 明 过 upstream 机 制 的 一 种 基础 用 法 ， 本 章 将 讨 
论 upstream 机 制 的 设计 和 实现 ， 以 此 帮助 读者 全 面 了 解 如 何 使 用 
upstream 访 问 上 游 服务 器 。upstream 机 制 是 事件 驱动 框架 与 HTTP 框架 
的 综合 ， 它 既 属于 HTTP 框 架 的 一 部 分 ， 又 可 以 处 理 所 有 基于 TCP 的 应 
用 层 协议 (不 限于 HTTP) 。 它 不 仅 没 有 任何 阻塞 地 实现 了 Nginx 与 上 
游 服 务 器 的 交互 ， 同 时 又 很 好 地 解决 了 一 个 请 求 、 多 个 TCP 连 接 、 多 
个 读 / 写 事件 间 的 复杂 关系 。 为 了 帮助 Nginx 实 现 反 向 代理 功能 ， 
upstream 机 制 除 了 提供 基本 的 与 上 游 交 互 的 功能 之 外 ， 还 实现 了 转发 
上 游 应 用 层 协 议 的 响应 包 体 到 下 游客 户 端的 功能 (与 下 游 之 间 当 然 还 
是 使 用 HTTP) 。 在 这 些 过 程 中 ，upstream 机 制 使 用 内 存 时 极其 “ 节 
省 ”， 特 别 是 在 转发 响应 包 体 时 ， 它 从 不 会 把 一 份 上 游 的 协议 包 复 制 多 
份 。 考 虑 到 上 下 游 间 网 速 的 不 对 称 ，upstream 机 制 还 提供 了 以 大 内 存 
和 磁盘 文件 来 缓存 上 游 响 应 的 功能 。 


因此 ， 拥 有 高 性 能 、 高 效率 以 及 高 度 灵 活性 的 upstream 机 制 值得 
我 们 花费 精力 去 了 解 它 的 设计 、 实 现 ， 这 样 才能 更 好 地 使 用 它 。 同 
时 ， 通 过 学 习 它 的 设计 思想 ， 也 可 以 深入 了 解 配 合 应 用 层 业 务 基于 第 9 
章 的 事件 框架 开发 Nginx 模 块 的 方法 。 


由 于 upstream 机 制 较为 复杂 ， 同 时 在 第 11 章 *HTTP 框 架 ” 中 我 们 已 
经 非常 熟悉 如 何 使 用 事件 驱动 染 构 了 ， 所 以 本 章 将 不 会 纠结 于 事件 驱 
动 架 构 的 细 方 、 分 支 ， 而 是 专注 于 upstream 机 制 的 主要 流程 。 也 就 是 
说 ， 本 章 将 会 略 过 处 理 upstream 的 过 程 中 超时 、 连 接 关 闭 、 失 败 后 重 
新 执行 等 非 核心 事件 ， 仅 聚焦 于 正常 的 处 理 过 程 (在 由 源 代 码 对 应 的 
流程 图 中 ， 就 是 会 把 许多 执行 失败 的 分 文 略 过 ， 对 于 这 些 错误 分 文 的 
执行 情况 ， 读 者 可 以 通过 阅读 ngx_http_upstream 源 代码 来 了 解 ) 。 虽 
然 upstream 机 制 也 包含 了 部 分 文件 缓存 功能 的 代码 ， 但 限于 篇 幅 ， 本 
草 将 不 介绍 文件 缓存 ， 这 部 分 内 容 也 会 直接 上 略 过 。 经 过 这 样 处 理 ， 读 
者 就 可 以 清晰 、 直 观 地 看 到 upstream 到 底 是 如 何 工作 的 了 ， 如 果 还 需 
要 了 解 细 下 ， 那 么 可 以 由 主要 流程 附近 的 相关 代码 查询 到 各 种 分 文 的 
QE/ 


Nginx 访 问 上 游 服务 硕 的 流程 大 致 可 以 分 为 以 下 6 个 阶段 : 局 动 
upstream 机 制 、 连 接 上 游 服 务 器 、 疝 上 游 服 务 器 发 送 请 求 、 接 收 上 游 
服务 器 的 响应 包头 、 处 理 接收 到 的 响应 包 体 、 结 束 请 求 。 本 章 首先 在 
12.1 攻 系统 地 讨论 upstream 机 制 的 设计 目的 ， 以 及 为 了 实现 这 些 目的 需 
要 用 到 的 数据 结构 ， 之 后 会 按照 顺序 介绍 上 述 6 个 阶段 。 


12.1 upstream 机 制 概 述 


本 十 将 说 明 upstream 机 制 的 设计 目的 ， 包 括 它 能 够 解决 哪儿 类 问 
题 。 接 下 来 吏 会 介绍 一 个 关键 结构 体 ngx_http_upstream_t 以 及 它 的 conf 
成 员 (ngx_http_upstream_conf t 结 构 体 ) ， 事 实 上 这 两 个 结构 体 中 的 
各 个 成 员 意 义 有 些 混 清 不 消 ， 有 些 仅 用 于 upstream 框 架 使 用 ， 有 些 却 
征 硕 望 使 用 upstream 的 HITP 模 块 来 设置 的 ， 这 也 征 C 语 言 编程 的 浆 
端 。 因 此 ， 如 有 果 硕 望 直 接 编写 使 用 upstream 机 制 的 复杂 模块 ， 可 以 采 
取 有 顺序 阅 读 的 方式 ， 如 采 硕 望 更 多 地 了 解 upstream 的 工作 流程 ， 则 不 
妨 先 跳 过 对 这 两 个 结构 体 的 详细 说 明 ， 继 续 向 下 了 解 upstream 流 程 ， 
在 流程 的 每 个 阶段 中 都 会 使 用 到 这 两 个 结构 体 中 的 成 员 ， 到 时 可 以 再 
返回 得 询 每 个 成 员 的 意义 ， 这 样 会 更 有 效率 。 


12.1.1 设计 目的 


那么 ， 到 底 什 么 是 upstream 机 制 ? 它 的 设计 目的 有 哪些 ? 先 来 看 
看 图 12-1。 


(1) 上 游 和 下 游 


12-1 中 出 现 了 上 游 和 下 游 的 概念 ， 这 是 从 Nginx 视 角 上 得 出 的 名 
词 ， 怎么 理解 呢 ? 我 们 不 妨 把 它 看 成 一 条 产业 链 ，Nginx 征 其 中 的 一 


环 ， 离 消费 者 近 的 环节 属于 下 游 ， 离 消费 者 远 的 环节 属于 上 游 。Nginx 
的 客户 端 可 以 是 一 个 浏 咒 嚣 ， 或 者 十 一 个 应 用 程序 ， 叉 或 者 是 一 个 服 
务 器 ， 对 于 Nginx 来 说 ， 它 们 都 属于 “下 游 "”，Nginx 为 了 实现 “下 游 ” 所 

需要 的 功能 ， 很 多 时 候 是 从 “上 游 ” 的 服务 器 获取 一 些 原材料 的 如 数 
据 库 中 的 用 户 信息 等 ) 。 图 12-1 中 的 两 个 英文 单词 ，upstream 表 示 上 

游 ， 而 downstream 表 示 下 游 。 因 此 ， 所 谓 的 upstream 机 制 就 是 用 来 使 

HTTP 模 块 在 处 理 客户 端 请 求 时 可 以 访问 < 上游 ”的 后 端 服务 右 。 


客户 六 ( Nginx 的 下 游 ) 


[HTTP 请 求 ] [基于 HTTP 的 downstream 吧 应 | 


NgInx 


[ 基于 TCP 的 请 求 ] [基于 TCP 的 upstream 啊 应 ] 


后 疾 服 务 人 各 ( Nginx 的 上 游 ) 


12-1 ” upstream 机 制 的 场景 示意 


(2) 上 游 服 务 器 提供 的 协议 


Nginx 不 仅仅 可 以 用 做 web 服务 器 。upstream 机 制 其 实 是 由 
ngx_http_upstream_module 模 块 实现 的 ， 它 是 一 个 HTTP 模 块 ， 使 用 
upstream 机 制 时 客户 端的 请 求 必须 基于 HTTP 。 


既然 upstream 是 用 于 访问 “上 游 ? 服 务 器 的 ， 那 么 ，Nginx 需 要 访问 
什么 类 型 的 上游? 服务 器 昵 ? 是 Apache、Tomcat 这 样 的 web 服务器 ， 
还 是 memcached、cassandra 这 样 的 Key-Value 存 储 系统 ， 又 或 是 
mongoDB、MYySQL 这 样 的 数据 库 ? 这 就 涉及 upstream 机 制 的 范围 了 。 
其 实 非常 明显 ， 回 顾 一 下 第 9 章 中 系统 介绍 过 的 主要 用 于 处 理 TCP 的 事 
件 驱 动 架 构 ， 基 于 事件 驱动 架构 的 upstream 机 制 所 要 访问 的 就 是 所 有 
支持 TCP 的 上 游 服务 器 。 因 此 ， 既 有 ngx_http_proxy_module 模 块 基于 
upstream 机 制 实现 了 HTTP 的 反 向 代理 功能 ， 也 有 类 似 
ngx_http_memcached_module 的 模块 基于 upstream 机 制 使 得 请 求 可 以 访 


问 memcached 服 务 器 。 


(3) 每 个 客户 端 请 求实 际 上 可 以 向 多 个 上 游 服务 器 发 起 请 求 


在 图 12-1 中 ， 似 乎 一 个 客户 端 请 求 只 能 访问 一 个 上 游 服 务 右 ， 事 
实 上 并 不 是 这 样 ， 否 则 Nginx 的 功能 就 太 弱 了 。 对 于 每 个 
ngx_http_request_t 请 求 来 说 ， 只 能 访问 一 个 上 游 服 务 器 ， 但 对 于 一 个 
客户 疾 请 求 来 说 ， 可 以 派生 出 许多 子 请 求 ， 任 何 一 个 子 请 求 痢 可 以 访 
问 一 个 上 游 服 务 器 ， 这 些 子 请 求 的 结果 组 合 起 来 区 可 以 使 来 目 客 户 端 
的 请 求 处 理 复 杂 的 业务 。 


可 为 什么 每 个 ngx_http_request_t 请 求 只 能 访问 一 个 上 游 服务 器 ? 
这 是 由 于 upstream 机 制 还 有 更 复杂 的 目的 。 以 反问 代理 功能 为 例 ， 
upstream 机 制 需 要 把 上 游 服务 器 的 响应 全 部 转发 给 客户 端 ， 那 么 如 果 
响应 的 长 度 特别 大 怎么 办 ? 例如 ， 用 户 下 载 一 个 5GB 的 视频 文件 ， 
upstream 机 制 肯 定 不 能 够 在 Nginx 接 收 了 完整 的 啊 应 后 ， 再 把 它 转发 给 
客户 端 ， 这 样 效率 太 差 了 。 因 此 ，upstream 机 制 不 只 提供 了 直接 处 理 
上 游 服 务 妖 啊 应 的 功能 ， 还 具有 将 来 自 上 游 服务 絮 的 啊 应 即时 转发 给 
下 游客 户 端 的 功能 。 因 为 有 了 这 个 独特 的 需求 ， 每 个 
ngx_http_request_t 结 构 体 只 能 用 来 访问 一 个 上 游 服务 器 ， 大 大 简化 了 


设计 。 
(4) 反 向 代理 与 转发 上 游 服务 器 的 响应 
转发 响应 时 则 样 有 两 个 需要 解决 的 问题 。 


1) 下 游 协 议 是 HTTP， 而 上 游 协 议 可 以 是 基于 TCP 的 任何 协议 ， 
这 需要 有 一 个 适 配 的 过 程 。 所 以 ，upstream 机 制 会 将 上 游 的 响应 划分 
为 包头 、 包 体 两 部 分 ， 包 头 部 分 必须 由 HTTP 模 块 实现 的 
process_header 方 法 解析 、 处 理 ， 包 体 则 由 upstream 不 做 修改 地 进行 转 
发 。 


2) 上 、 下 游 的 网 速 可 能 差别 非常 大 ， 通 常 在 产品 环境 中 ，Nginx 
与 上 游 服 务 器 之 间 是 内 网 ， 网 速 会 很 快 ， 而 Nginx 与 下 游 的 客户 端 之 间 


则 征 公 网 ， 网 速 可 能 非常 慢 。 对 于 这 种 情况 ， 将 会 有 以 下 两 种 解决 方 


类 


- 当 上 、 下 游 网 速 差 距 不 大 ， 或 者 下 游 速 度 更 快 时 ， 出 于 能 够 并 发 
更 多 请 求 的 考虑 ， 必 然 布 望 内 存 可 以 使 用 得 少 一 些 ， 这 时 将 会 开辟 一 
块 固定 大 小 的 内 存 (由 ngx_http_upstream_conf t 中 的 buffer_size 指 定 大 
小 ) ， 既 用 它 来 接收 上 游 的 响应 ， 也 用 它 来 把 保存 的 响应 内 容 转 发 给 
下 族 。 这 样 做 也 是 有 人 缺点 的 ， 当 下 游 速度 过 慢 而 导致 这 块 充当 缓冲 区 
的 内 存 写 满 时 ， 将 无 法 再 接收 上 游 的 啊 应 ， 必 须 等 待 缓冲 区 中 的 内 容 
全 部 发 送 给 下 游 后 才能 继续 接收 。 


` 当 上 游 网 速 远 快 于 下 游 网 速 时 ， 就 必须 要 开辟 足够 的 内 存 缓冲 区 
来 缓存 上 游 响应 ngx_http_upstream_conf t 中 的 bufs 指 定 了 每 块 内 存 缓 
冲 区 的 大 小 ， 以 及 最 多 可 以 有 多 少 块 内 存 缓冲 区 ) ， 当 达到 内 存 使 用 
上 限时 还 会 把 上 游 响 应 缓存 到 磁盘 文件 中 〈 当 然 ， 人 磁盘 文件 也 是 有 大 
小 限制 的 ，ngx_http_upstream_conf_t 中 的 max_temp_file_size 指 定 了 临 
时 缓存 文件 的 最 大 长 度 ) ， 虽 然 内 存 和 人 磁 副 的 缓冲 都 满 后 ， 仍 然 会 发 
生 暂 时 无 法 接收 上 游 响 应 的 场景 ， 但 这 种 概率 就 小 得 多 了 ， 特 别 是 临 
时 文件 的 上 限 设置 得 较 大 时 。 


转发 啊 应 时 一 个 比较 难以 解决 的 问题 是 Nginx 对 内 存 使 用 得 太 “F 
省 ”， 即 从 来 不 会 把 接收 到 的 上 游 啊 应 缓冲 区 复制 为 两 份 。 这 整 市 来 了 
一 个 问题 ， 当 同一 块 缓冲 区 既 用 于 接收 上 游 啊 应 ， 又 用 于 向 下 游 发 送 


啊 应 ， 同 时 可 能 还 在 写 入 临时 文件 ， 那 么 ， 这 块 缓冲 区 何 时 可 以 释 

放 ， 以 便 接 收 新 的 缓冲 区 呢 ? 对 于 这 个 问题 ，Nginx 是 采用 多 

ngx_buf_t 结 构 体 指 癌 同一 块 内 存 的 做 法 来 解决 的 ， 并 且 这 些 ngx_buf _t 

缓冲 区 的 shadow 域 会 互相 引用 ， 以 确保 真实 的 缓冲 区 真 的 不 再 使 用 时 
会 回收 ~ 复 用 。 


12.1.2 ngx_http_upstream_t 数 据 结构 的 意义 


使 用 upstream 机 制 时 必须 构造 ngx_http_upstream_t 结 构 体 ， 下 面 详 
述 其 中 每 个 成 员 的 意义 。 


typedef struct ngx_http_upstream_s ngx_http_upstream t,; 
struct ngx_http_upstream s { 


// 处 理 读 事件 的 回调 方法 ， 每 一 个 阶段 都 有 不 同 的 


read_event_handler 
ngx_ http_ upstream_handler_pt read event_handler; 
// 处 理 写 事件 的 回调 方法 ， 每 一 个 阶段 都 有 不 同 的 


write_ event_handler 
ngx_ http_ Upstream_handler_pt write event_handler,; 


/* 表 示 主 动向 上 游 服 务 器 发 起 的 连接 。 关 于 


ngx_peer_connection_t 结 构 体 ， 可 参见 


二 


9.3.21 


*/ 
ngx_peer_connection_t peer,; 
// 当 向 下 游客 户 端 转发 响应 时 ( 


ngx_http_request_t 结 构 体 中 的 


subrequest_in_memory 标 志 位 为 


9) ， 如 果 打 开 了 缓存 且 认 为 上 游 网 速 更 ' 


re 


sa 


conf 配 置 中 的 


buffering 标 志 位 为 


1) ， 这 时 会 使 


pipe 成 员 来 转发 响应 。 在 使 用 这 种 方式 转发 响应 时 ， 必 须 由 


HTTP 模 块 在 使 用 


upstream 机 制 前 构造 


pipe 结 构 体 ， 否 则 会 出 现 严 重 的 
coredump 错 误 。 详 见 

12 .8 .1 

< 


ngx_event_pipe_t *pipe; 


// 定义 了 向 下 游 发 送 响 应 的 方式 


ngx_output_chain ctx_t output; 
ngx_chain writer_ctx t writer; 
// 使 用 


upstream 机 制 时 的 各 种 配置 ， 详 见 


12.1.3 节 
ngx_http_upstream conf_t *conf; 
/A*HTTP 模 块 在 实现 
process_header 方 法 时 ， 如 果 希 望 
upstream 直 接 转发 响应 ， 就 需要 把 解析 出 的 响应 头 部 适 配 为 
HTTP 的 响应 头 部 ， 同 时 需要 把 包头 中 的 信息 设置 到 
headers_in 结 构 体 中 ， 这 样 ， 在 图 
12-5 的 第 


8 步 中 ， 会 把 


headers_in 中 设置 的 头 部 添加 到 要 发 送 到 下 游客 户 端的 响应 头 部 


headers_out 中 


*/ 
ngx_http_upstream headers_in t headers _ in; 


// 用 于 解析 主机 域名 ， 本 章 不 作 介绍 


ngx_http_upstream resolved t *resolved ; 


/* 接 收 上 游 服 务 器 响应 包头 的 缓冲 区 ， 在 不 需要 把 响应 ] 


buffering 标 志 位 为 
9 的 情况 下 转发 包 体 时 ， 接 收 包 体 的 缓 ; 


buffer。 注 意 ， 如 果 没 有 自 定 义 


input_filter 方 法 处 理 包 体 ， 将 会 使 用 


接 转 发 给 客 


户 端 ， 或 者 


buffer 存 储 全 部 的 包 体 ， 这 时 
buffer 必 须 足 够 大 ! 它 的 大 小 


ngx_http_upstream_conf_t 配 置 结构 体 中 的 


buffer_size 成 员 决 定 


*/ 
ngx_buf_t buffer,; 
// 表示 来 自 上 游 服 务 器 的 响应 包 体 的 长 度 


size_t length; 
/* out_bufs 在 两 种 场景 下 有 不 同 的 意义 : 中 当 不 需要 转发 包 体 ， 且 使 用 默认 的 


input_filter 方 法 (也 就 是 
ngx_http_upstream_non_buffered_filter 方 法 ) 处 理 包 体 时 ， 


out_bufs 将 会 指向 响应 包 体 ， 事 实 上 ， 


out_bufs 链 表 中 会 产生 多 个 


ngx_buf_t 缓 冲 区 ， 每 个 缓冲 区 都 指向 
buffer 缓 存 中 的 一 部 分 ， 而 这 里 的 一 部 分 就 是 每 次 调用 
recv 方 法 接收 到 的 一 段 

TCP 流 。@@ 当 需要 转发 响应 包 体 到 下 游 时 ( 


buffering 标 志 位 为 


9， 即 以 下 游 网 速 优 先 ， 参 见 
12 .7 节 ) ， 这 个 链表 指向 上 一 次 向 下 游 转发 响应 到 现在 这 段 时 间 内 接收 自 上 游 的 缓存 响应 


SS/ 
ngx_chain t *out_bufs; 
/* 当 需要 转发 响应 包 体 到 下 游 时 ( 


buffering 标 志 位 为 


0， 即 以 下 游 网 速 优先 ， 参 见 
12.7 节 ) ， 它 表示 上 一 次 向 下 游 转发 响应 时 没有 发 送 完 的 内 容 


六 
ngx_chain t *busy_bufs; 
/* 这 个 链表 将 用 于 回收 


out_bufs 中 已 经 发 送 给 下 游 的 


时 


ngx_buf_t 结 构 体 ， 这 同样 应 
buffering 标 志 位 为 


9 即 以 下 游 网 速 优先 的 场景 


7 
ngx_chain t *free_ bufs; 


/* 处 理 包 体 前 的 初始 化 方法 ， 其 中 


data 参 数 用 于 传递 用 户 数据 结构 ， 它 实际 上 就 是 下 面 的 


input_filter_ctx 指 针 


4 


ngx_int_t (*input_ filter_ init)(void *data); 


/* 处 理 包 体 的 方法 ， 其 中 
data 参 数 用 于 传递 用 户 数据 结构 ， 它 实际 上 就 是 下 面 的 


input_filter_ctx 指 针 ， 而 


bytes 表 示 本 次 接收 到 的 包 体 长 度 。 返 回 


NGX_ERROR 时 表示 处 理 包 体 错 误 ， 请 求 需要 结束 ， 否 则 都 将 继续 
upstream 流 程 
ngx_int_t (*input_filter)(void *data，SSsize_t bytes ) 


/* 用 于 传递 


HTTP 模 块 自 定义 的 数据 结构 ， 在 


input_filter_init 和 


input_filter 方 法 被 回调 时 会 作为 参数 传递 过 去 


* 
/ 
void *input_filter_ctx; 
// HTTP 模 块 实现 的 


create_request 方 法 用 于 构造 发 往 上 游 服务 器 的 请 求 


ngx_int_t (*create request)(ngx_http_request _t *r); 


/* 与 上 游 服务 器 的 通信 失败 后 ， 如 果 按照 重 试 规则 还 需要 再 次 向 上 游 服 务 器 发 起 连接 ， 则 会 调用 


reinit_request 方 法 


*/ 
ngx_int_t (*reinit request)(ngx_http_request t *r); 


/* 解 析 上 游 服 务 器 返回 响应 的 包头 ， 返 区 


五 


NGX_AGAIN 表 示 包 头 还 没有 接收 完整 ， 返 


NGX_HTTP_UPSTREAM_INVALID_HEADER 表 示 包 头 不 合法 ， 返 回 


NGX_ERROR 表 示 出 现 错误 ， 返 回 


NGX_0K 表 示 解 析 到 完整 的 包头 


ngx_int_t (*process header)(ngx_http_request t *r); 
// 当前 版 本 下 


abort_request 回 调 方 法 没有 任意 意义 ， 在 


upstream 的 所 有 流程 中 都 不 会 调 


*/ 
void (*abort_request)(ngx_http_request t *r); 
// 请 求 结束 时 会 调用 ， 参 见 
12.9.1 节 
void (*finalize request)(ngx_http_request t *r, 
ngx_int_t rc); 
/* 在 上 游 返 回 的 响应 出 现 
Location 或 者 


Refresh 头 部 表示 重 定向 时 ， 会 通过 


ngx_http_upstream_process_headers 方 法 (参见 图 


12-5 中 的 第 
8 步 ) 调用 到 可 由 


HTTP 模 块 实现 的 
rewrite_redirect 方 法 


*/ 
ngx_int_t (*rewrite redirect)(ngx_http_request t *r, 
ngx_table elt_t *h, size_t prefix); 
// 暂 无 意义 


ngx_msec_t timeout 
// 用 于 表示 上 游 响应 的 错误 码 、 包 体 长 度 等 信息 


ngx_http_upstream state t *state,; 
// 不 使 用 文件 缓存 时 没有 意义 


ngx_str_t method ; 
// schema 和 


uri 成 员 仅 在 记录 日 志 时 会 用 到 ， 除 此 以 外 没有 意义 


ngx_str_t schema; 
ngx_str_t uri; 
/* 目 前 它 仅 用 于 表示 是 否 需要 清理 


涡 


源 ， 相 当 于 一 个 标志 位 ， 实 际 不 会 调用 到 它 所 指向 的 方法 


*/ 
ngx_http_cleanup_pt *cleanup; 
// 是 否 指定 文件 缓存 路 径 的 标志 位 ， 本 章 不 讨论 文件 缓存 ， 略 过 


unsigned store:1,; 
// 是 否 启用 文件 缓存 ， 本 章 仅 讨论 


cacheable 标 志 位 为 


0 的 场景 


unsigned cacheable:1,; 
// 和 暂 无 意义 


unsigned accel:1,; 
// 是 否 基 于 


SSL 协 议 访问 上 游 服 务 器 


unsigned ssl:1; 
/* 向 下 游 转 发 上 游 的 响应 包 体 时 ， 是 否 开启 更 大 的 内 存 及 临时 磁盘 文件 用 于 缓存 来 不 及 发 送 到 下 游 的 响应 
包 


*/ 


unsigned buffering:1,; 
/*request_bufs 以 链表 的 方式 把 


ngx_buf_t 缓 冲 区 链接 起 来 ， 它 表示 所 有 需要 发 送 到 上 游 服 务 器 的 请 求 内 容 。 所 以 ， 


HTTP 模 块 实现 的 


create_request 回 调 方法 就 在 于 构造 


ba 


redquest_bufs 链 对 


* 
ngx_chain_t *request_bufs ; 
/*redquest_sent 表 示 是 否 已 经 向 上 游 服务 器 发 送 了 请 求 ， 当 


request_sent 为 


1 时 ， 表 示 
upstream 机 制 已 经 向 上 游 服 务 器 发 送 了 全 部 或 者 部 分 的 请 求 。 事 实 上 ， 这 个 标志 位 更 多 的 是 为 了 使 
ngx_output_chain 方 法 发 送 请 求 ， 因 为 该 方法 发 送 请 求 时 会 自动 把 未 发 送 完 的 

request_bufs 链 表 记 录 下 来 ， 为 了 防止 反复 发 送 重复 请 求 ， 必 须 有 


request_sent 标 志 位 记录 是 否 调 用 过 
ngx_output_chain 方 法 
二 


unsigned request_ sent:1; 


/* 将 上 游 服务 器 的 响应 划分 为 包头 和 包 尾 ， 如 果 把 响应 直接 转发 给 客户 端 ， 


header_sent 标 志 位 表示 包头 是 否 发 送 ， 


header_sent 为 


1 时 表示 已 经 把 包头 转发 给 客户 端 了 。 如 果 不 转 发 响应 到 客户 端 ， 则 


header_sent 没 有 意义 


WA 


unsigned header_sent:1; 


到 目前 为 止 ，ngx_http_upstream_t 结 构 体 中 有 些 成 员 仍 然 没 有 使 用 
到 ， 还 有 更 多 的 成 员 其 实 仅 是 HTTP 框 架 自 己 使 用 ，HTTP 模 块 在 使 用 
upstream 时 需要 设置 的 成 员 并 不 是 太 多 ， 但 在 实现 process_header、 
input_filter 等 回调 方法 时 ， 还 是 需要 对 各 个 成 员 有 一 个 初步 的 了 解 ， 这 
样 才能 高 效 地 使 用 upstream 机 制 。 


12.1.3 ”ngx_http_upstream_conf _t 配 置 结构 体 


ngx_http_upstream_t 结 构 体 中 的 conf 成 员 是 非常 关键 的 ， 它 指定 了 
upstream 有 的 运行 方式 。 注 意 ， 它 必须 在 启动 upstream 机 制 前 设置 。 下 面 
来 看 看 这 个 结构 体 中 各 个 成 员 的 意义 。 


typedef struct { 
/* 当 在 


ngx_http_upstream_t 结 构 体 中 没有 实现 


resolved 成 员 时 ， 


upstream 这 个 结构 体 才 会 生效 ， 它 会 定义 上 游 服务 器 的 配置 


eh 
ngx_http_upstream_ srv_conf_t *upstream; 


TCP 连 接 的 超时 时 间 ， 实 际 上 就 是 写 事 件 添加 到 定时 器 中 时 设置 的 超时 时 间 ， 参 见 图 
12-3 中 的 第 


8 步 


*/ 
ngx_msec_t connect_timeout; 


/* 发 送 请 求 的 超时 时 间 。 通 常 就 是 写 事件 添加 到 定时 器 中 设置 的 超时 时 间 ， 参 见 图 
12-4 中 的 第 


3 步 
*/ 
ngx_msec_t Send_timeout 
/* 接 收 响应 的 超时 时 间 。 通 常 就 是 读 事件 添加 到 定时 器 中 设置 的 超时 时 间 ， 参 见 银 
12-4 中 的 第 


5 步 


7 
ngx_msec_t read timeout,; 
// 目前 无 意义 


ngx_msec_t timeout,; 
// TCP 的 


SO_SNOLOWAT 选 项 ， 表 示 发 送 缓冲 区 的 下 限 


size_t Send_]lowat 


/* 定 义 了 接收 头 部 的 缓冲 区 分 配 的 内 存 大 小 ( 


ngx_http_upstream_t 中 的 


buffer 缓 冲 区 ) ， 当 不 转发 响应 给 下 游 或 者 在 


buffering 标 志 位 为 


9 的 情况 下 转发 响应 时 ， 它 同样 表示 接收 包 体 的 缓冲 区 大 小 


4 
size_t buffer_size,; 
/* 仅 当 
buffering 标 志 位 为 


1， 并 且 向 下 游 转发 响应 时 生 


六 
湾 


它 会 设置 到 


o 


ngx_event_pipe_t 结 构 体 的 


busy_size 成 员 中 ， 具 体 含义 参见 
12.8.1 节 
*/ 

size_t busy_buffers_size; 


/在 


buffering 标 志 位 为 


1 时 ， 如 果 上 游 速度 快 于 下 游 速度 ， 将 有 可 能 把 来 自 上 游 的 响应 存储 到 临时 文件 中 ， 而 


max_temp_file_size 指 定 了 临时 文件 的 最 大 长 度 。 实 际 上 ， 它 将 限制 
ngx_event_pipe_t 结 构 体 中 的 


temp_file*/ 
size _t max_ temp_file size; 


// 表示 将 组 六 


Et 


size_t temp_file write size; 


// 以 下 


3 个 成 员 


前 都 没有 任何 意义 


size_t busy_buffers_size_conf,; 
size_t max_temp_file_ size_ conf; 
size_t temp_file write size_ conf; 


// 以 缓存 响应 的 方式 转发 上 游 服务 器 的 包 体 时 所 使 


H 


ngx_bufs_t bufs ， 


A* 镍 


对 


ngx_http_upstream_t 结 构 体 中 保存 解析 完 的 包头 的 


headers_in 成 员 ， 


ignore_headers 可 以 按照 二 进 制 位 使 得 


upstream 在 转发 包头 时 跳 过 对 某 些 头 部 的 处 到 


32 位 整 型 ， 


HB 


。 作 为 


理论 上 


ignore_headers 最 多 可 以 表示 
32 个 需要 跳 过 不 予 处 理 的 头 部 ， 然 而 目前 


upstream 机 制 仅 提供 


8 个 位 


8 个 


于 忽略 


HTTP 头 部 的 处 理 ， 包 括 : 


#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 

ngx 


/* 以 二 进 制 位 来 表示 一 些 错误 码 ， 如 果 处 理 上 游 响应 时 发 现 这 些 错误 码 ， 那 么 在 没 
端 时 ， 将 会 选择 下 一 个 上 游 服务 器 来 重 发 请 求 。 参 见 


户 立 


NGX_HTTP_UPSTREAM_IGN XA_ REDIRECT 
NGX_HTTP_UPSTREAM_IGN XA_ EXPIRES 
NGX_HTTP_UPSTREAM_IGN_EXPIRES 
NGX_HTTP_UPSTREAM_IGN_CACHE_CONTROL 
NGX_HTTP_UPSTREAM_IGN_SET_COOKIE 
NGX_HTTP_UPSTREAM_IGN_XA_LIMIT_RATE 
NGX_HTTP_UPSTREAM_IGN_XA_BUFFERING 
NGX_HTTP_UPSTREAM_IGN_XA_CHARSET 
uint_t ignore_ headers,; 


x 中 的 响应 写 入 临时 文件 时 一 次 写 入 字符 流 的 最 大 长 度 


用 的 内 存 大 小 


0OX00000002 
0X00000004 
0X00000008 
0X00000010 
0OX00000020 
OxOQ0000040 
0OX00000080 


Ox00000100*/ 


12 .9 节 中 介绍 的 


ngx_http_upstream_next 方 法 


4 


ngx_uint_t next_upstream; 


/* 在 


将 响应 转发 给 下 游客 


buffering 标 志 位 为 


CC 


把 响应 存放 到 临时 文件 中 。 在 


录 、 文 件 的 权限 


1 时 表示 打开 缓存 ， 这 时 认为 上 游 的 网 速 快 于 下 游 的 网 速 ， 会 尽量 地 在 内 存 或 者 磁盘 中 缓存 来 自 上 游 的 响应 ; 如 


块 固 定 大 小 的 内 存 块 作为 缓存 来 转发 响应 


1 的 情况 下 转发 响应 时 ， 将 有 可 色 
ngx_http_upstream t 中 的 
store 标 志 位 为 
1 时 ， 
store_access 表 示 所 创建 的 
Wh 
ngx_uint_t store access; 
/* 决 定 转 发 响应 方式 的 标志 位 ， 
buffering 为 
果 
buffering 为 
9， 仅 会 开辟 
A 


ngx_flag_t buffering,; 
// 暂 无 意义 


ngx_flag_t pass_request_headers ; 
// 暂 无 意义 


ngx_flag_t pass_request_body; 
/* 表 示 标 志 位 。 当 它 为 


1 时 ， 表 示 与 上 游 服务 器 交互 时 将 不 检查 
Nginx 与 下 游客 户 端 间 的 连接 是 


器 间 的 交互 


*/ 


否 断 


。 也 就 是 说 ， 即 使 下 游客 户 端 主动 关闭 了 连接 


雪 


ngx_flag_t ignore client abort; 
/* 当 解析 上 游 响应 的 包头 时 ， 如 果 解 析 后 设置 到 


headers_in 结 构 体 中 的 


status_n 错 误 码 大 于 


400， 则 会 试图 把 它 与 


error_paged 


error_pagej 


指定 的 错误 码 相 


匹配 ， 如 果 1 


匹配 上 ， 则 发 送 


FP 指定 的 响应 ， 否 


则 继续 返 


口 


上 游 服务 器 的 错误 码 。 详 见 


ngx_http_upstream_intercept_errors 方 法 


4 


ngx_flag_t intercept_errors,; 


/*buffering 标 志 位 为 


， 也 不 会 中 断 与 上 游 服务 


1 的 情况 下 转发 响应 时 才 有 意义 。 这 时 ， 如 果 


cyclic _ temp_file 为 


1， 则 会 试图 复 用 临时 文件 中 已 经 使 用 过 的 空间 。 不 建议 将 


cyclic_temp_file 设 为 


1*/ 
ngx_flag_t cyclic temp_ file; 
// 在 


buffering 标 志 位 为 


1 的 情况 下 转发 响应 时 ， 存 放 临 时 文件 的 路 径 


ngx_path_t *temp_path ; 
/* 不 转发 的 头 部 。 实 际 上 是 通过 


ngx_http_upstream_hide_headers_hash 方 法 ， 根 据 


hide_headers 和 


pass_headers 动 态 数 组 构造 出 的 需要 隐藏 的 


HTTP 头 部 散 列 表 

*/ 
ngx_hash_t hide_headers_hash; 
/* 当 转发 上 游 响 应 头 部 ( 


ngx_http_upstream t 中 


headers_in 结 构 体 中 的 头 部 ) 给 下 游客 户 端 时 ， 如 果 不 希 望 某 些 头 部 转发 给 下 游 ， 就 设置 到 


hide_headers 动 态 数 组 中 


“A 
ngx_array_t *hide_ headers; 


/* 当 转发 上 游 响 应 头 部 人 


ngx_http_upstream_t 中 
headers_in 结 构 体 中 的 头 部 ) 给 下 游客 户 端 时 ， 
upstream 机 制 默认 不 会 转发 如 “ 


El 


Date”、“ 


Server” 之 类 的 头 部 ， 如 果 确 实 希 望 直接 转发 它们 到 下 游 ， 就 设置 到 


pass_headers 动 态 数 组 中 


6 
ngx_array_t *pass_ headers; 


// 连接 上 游 服务 器 时 使 用 的 本 机 地 址 


ngx_addr_t *local; 


/* 当 
ngx_http_upstream_t 中 的 
store 标 志 位 为 


1 时 ， 如 果 需 要 将 上 游 的 响应 存放 到 文件 


UD 


store_lengths 将 表示 存放 路 径 的 长 度 ， 而 


store_values 表 示 存 放 路 径 


人 
ngx_array_t *store_lengths,; 
ngx_array_t *store values; 
/* 到 目前 为 止 ， 


store 标 志 位 的 意义 与 


ngx_http_upstream_t 中 的 


store 相 同 ， 仍 只 有 


9 和 


1 被 使 用 到 


signed store:2; 
/* 上 面 的 


intercept_errors 标 志 位 定义 了 
4600 以 上 的 错误 码 将 会 三 


error_page 比 较 后 再 行 处 理 ， 实 际 上 这 个 规则 是 可 以 有 一 个 例外 情况 的 ， 如 果 将 


intercept_404 标 志 位 设 为 


1， 当 上 游 返 世 


404 时 会 直接 转发 这 个 错误 码 给 下 游 ， 而 不 会 去 与 


error_page 进 行 比较 

4 
unsigned intercept 404:1; 
/* 当 该 标志 位 为 


1 时 ， 将 会 根据 


ngx_http_upstream t 中 
headers_in 结 构 体 里 的 
X-Acce1L-Buffering 头 部 ( 它 的 值 会 是 
yes 和 


no) 来 改变 


buffering 标 志 位 ， 当 其 值 为 


yes 时 ， 


buffering 标 志 位 为 


1。 因 此 ， 


change_buffering 为 


1 时 将 有 可 能 根据 上 游 服务 器 返回 的 响应 头 部 ， 动 态 地 决定 是 以 上 游 网 速 优先 还 是 以 下 游 网 速 优先 
*/ 


unsigned change_buffering:1; 
// 使 


upstream 的 模块 名 称 ， 仅 用 于 记录 日 志 


ngx_str_t module,; 
} ngx_http_upstream conf_t,; 


ngx_http_upstream_conf t 结 构 体 中 的 配置 都 比较 重要 ， 它 们 会 影 
响 访 问 上 游 服务 器 的 方式 。 同 时 ， 该 结构 体 中 的 大 量 成 员 是 与 如 何 转 
发 上 游 响 应 相关 的 。 如 果 用 户 希 望 直 接 转发 上 游 的 包 体 到 下 游 ， 那 就 
需要 注意 ngx_http_upstream_conf t 中 每 一 个 成 员 的 意义 了 。 


dN 


12.2 ”局 动 upstream 


在 把 请 求 里 ngx_http_request_t 结 构 体 中 的 upstream 成 员 
ngx_http_upstream_t 类 型 ) 创建 并 设置 好 ， 并 且 正 确 设置 upstream- 
>conf 配 置 结 构 体 (ngx_http_upstream_conf t 类 型 ) 后， 就 可 以 启动 
upstream 机 制 了 。 局 动 方式 非常 答 单 ， 调 用 ngx_http_upstream_init 方 法 
即 可 。 


注意 ， 默 认 情 况 下 请 求 的 upstream 成 员 只 是 NULL 空 指针 ， 在 设置 
up stream 之 前 需要 调 用 ngx_http_up stream_create 方 法 从 内 存 池 中 创建 
ngx_http_upstream_t 结 构 体 ， 该 方法 的 原型 如 下 。 


ngx_int_t ngx_http_upstream create(ngx_http_request_t *r) 


ngx_http_upstream_create 方 法 只 是 创建 ngx_http_upstream _t 结 构 体 
而 已 ， 其 中 的 成 员 还 需要 各 个 HTTP 模 块 自行 设置 。 启 动 upstream 机 制 
的 ngx_http_upstream_init 方 法 定义 如 下 。 


void ngx_http_upstream init(ngx_http_request_t *r) 


ngx_http_upstream_init 方 法 将 会 根据 ngx_http_upstream_conf_t 中 的 
成 员 初 始 化 upstream， 同 时 会 开始 连接 上 游 服 务 器 ， 以 此 展开 整个 


upstream 处 理 流 程 。 图 12-2 简 要 摘 述 了 ngx_http_upstream_init 方 法 所 做 
的 主要 工作 。 


[检查 下 游 ; 


[ 读 事 件 在 定时 器 中 ] 


1) 将 客户 端 连接 的 读 事件 由 \[ 读 事件 不 在 定时 需 中 ] 
定时 器 中 移 除 
[检查 ignore chent_abort 配 置 ] 


[ignore_client_abort 为 1] 
[ignore_client_abort 为 0] 


2 ) 设 置 检查 Nginx 
与 下 游客 户 端 连接 状态 的 方法 


3 ) 调 用 HTTP 模 块 实现 的 


create_request 方 法 


4) 将 ngx_http_upstream_cleanup 
方法 添加 到 cleanup 链 表 


5) 调用 ngx_http_upstream_connect 


方法 连接 上 游 服 务 郁 


图 12-2 ngx_http_upstream_init 方 法 的 流程 图 
下 面 依次 说 明 图 12-2 中 各 个 步骤 的 意义 。 


1) 首先 检查 请 求 对 应 于 客户 端的 连接 ， 这 个 连接 上 的 读 事 件 如 果 
在 定时 万 中 ， 也 束 是 说 ， 读 事件 的 timer_set 标 志 位 为 1， 那 么 调用 
ngx_del_timer 方 法 把 这 个 读 事 件 从 定时 万 中 移 除 。 为 什么 要 做 这 件 事 
呢 ? 因为 一 旦 局 动 upstream 机 制 ， 融 不 应 该 对 客户 端的 读 操 作 市 有 超时 
时 间 的 处 理 ， 请 求 的 主要 触发 事件 将 以 与 上 游 服 务 如 的 连接 为 主 。 


2) 检查 ngx_http_upstream_conf _t 配 置 结构 中 的 ignore_client_abort 
标志 位 (参见 12.1.3 节 ) ， 如 果 ignore_client_abort 为 1， 则 跳 到 第 3 步 ， 
否则 (实际 上 ， 还 需要 让 store 标 志 位 为 0、 请 求 ngx_http_request_t 结 构 
体 中 的 post_action 标 志 位 为 0) 束 会 设置 Nginx 与 下 游客 户 问 之 间 TCP 连 
接 的 检查 方法 ， 如 下 所 示 。 


r->read_event_handler = ngx_http_upstream_rd_check_broken_connection' 
r->write_event_handler = ngx_http_upstream wr_check_broken_connection,; 


实际 上 ， 这 两 个 方法 都 会 通过 
ngx_http_upstream_check_broken_connection 方 法 检查 Nginx 与 下 游 的 连 


接 是 否 正常 ， 如 有 果 出 现 错误 ， 就 会 立即 终止 连接 。 


3) 调用 请 求 中 ngx_http_upstream_t 结 构 体 里 由 某 个 HTTP 模 块 实现 
的 create_request 方 法 ， 构 造 发 往 上 游 服 务 器 的 请 求 (请 求 中 的 内 容 是 设 


置 到 request_bufs 绥 冲 区 链表 中 的 )  。 如 果 create_request 方 法 没有 返回 
NGX_OK， 则 upstream 机 制 结束 ， 此 时 会 调用 11.10.6 节 中 介绍 过 的 


ngx_http_finalize_request 方 法 来 结束 请 求 。 


4) 在 11.10.2 节 中 介绍 过 ，ngx_http_cleanup_t 是 用 于 清理 资源 的 结 
构 体 ， 还 说 明了 它 何 时 会 被 执行 。 在 这 一 步 中 ，upstream 机 制 束 用 到 了 
ngx_http_cleanup_t°。 首先， 调用 ngx_http_cleanup_add 方 法 同 这 个 请 求 
main 成 员 指 疝 的 原始 请 求 中 的 cleanup 链 表 末 尾 添 加 一 个 狐 成 员 ， 然 后 
把 handler 回 调 方法 设 为 ngx_http_upstream_cleanup， 这 意味 着 当 请 求 结 


束 时 ， 一 定 会 调用 ngx_http_upstream_cleanup 方 法 〈 参 见 12.9.1T) 。 


5) 调用 ngx_http_upstream_connect 方 法 向 上 游 服务 器 发 起 连接 ( 详 
见 12.3 节 ) 。 


人 @@ 注意。 启动 upstream 机 制 时 还 有 许多 分 支流 程 ， 如 缓存 文件 的 
使 用 、 上 游 服务 器 地 址 的 选取 等 ， 图 12-2 概 括 了 最 主要 的 5 个 步 又， 这 
样 方便 读者 了 解 upstream 的 核心 思想 。 其 他 分 支 的 处 理 不 影响 这 5 个 主 
要 流程 ， 如 需 了 解 可 自行 查看 ngx_http_upstream_init 和 


ngx_http_upstream_init_request 方 法 的 源 代码 。 


12.3 与 上 游 服务 右 建 立 连接 


upstream 机 制 与 上 游 服务 器 是 通过 TCP 建 立 连接 的 ， 众 所 周知 ， 建 
并 TCP 连 接 需 要 三 次 握手 ， 而 三 次 握手 消耗 的 时 间 是 不 可 控 的 。 为 了 
保证 建立 TCP 连 接 这 个 操作 不 会 阻塞 进程 ，Nginx 使 用 无 阻塞 的 套 接 字 
来 连接 上 游 服务 右 。 图 12-2 的 第 5 步调 用 的 ngx_http_upstream_connect 
方法 就是 用 来 连接 上 游 服 务 器 的 ， 由 于 使 用 了 非 阻 塞 的 套 接 字 ， 当 方 
法 返回 时 与 上 游 之 间 的 TCP 连 接 示 必 会 成 功 建立 ， 可 能 还 需要 等 待 上 
游 服 务 絮 返回 TCP 的 SYN/ACK 包 。 因 此 ,ngx_http_upstream_connect 
方法 主要 负责 发 起 建立 连接 这 个 动作 ， 如 果 这 个 方法 没有 了 立刻 返回 成 
功 ， 那么 需要 在 epoll 中 监控 这 个 套 接 字 ， 当 它 出 现 可 写 事 件 时 ， 就 说 
明 连 接 已 经 建立 成 功 了 。 


在 图 12-3 中 可 以 看 到 ， 如 采 连 毛 立 刻 成 功 建立 ， 在 第 9 步 束 会 开始 
问 上 谤 服务 器 发 送 请 求 ， 如 采 连 接 没 有 马上 建立 成 功 ， 在 第 8 步 吏 会 将 
这 个 连接 的 写 事件 加 入 到 epol 中 ， 等 竺 连接 上 的 可 写 事 件 被 触发 后 ， 
回调 ngx_http_upstream_send_request 方 法 发 送 请 求 给 上 游 服 务 器 


下 面 详 细 说 明 图 12-3 中 每 个 步骤 的 意义 。 


1) 调用 socket 方 法 建立 一 个 TCP 套 接 字 ， 同 时 ， 这 个 套 接 字 需要 
设置 为 非 阻塞 模式 。 


2) 由 于 Nginx 的 事件 框架 要 求 每 个 连接 都 由 一 个 ngx_connection_t 
结构 体 来 承载 ， 因 此 这 一 步 将 调用 ngx_get_connection 方 法 ， 由 
ngx_cycle_t 核 心 结构 体 中 free_connections 指 向 的 空闲 连接 池 处 获取 到 
一 个 ngx_connection_t 结 构 体 ， 作 为 承载 Nginx 与 上 游 服 务 器 间 的 TCP 连 


过 


3) 第 9 章 我 们 介绍 过 事件 模块 的 ngx_event_actions 接 口 ， 其 中 的 
add_conn 方 法 可 以 将 TCP 套 接 字 以 期 待 可 读 、 可 写 事 件 的 方式 添加 到 
事件 搜集 器 中 。 对 于 epoll 事 件 模块 来 说 ，add_conn 方 法 就 是 把 套 接 字 
以 期 待 EPOLLIN|EPOLLOUT 事 件 的 方式 加 入 epoll 中 ， 这 一 步 即 调用 
add_conn 方 法 把 刚刚 建立 的 套 接 字 添加 到 epoll 中 ， 表 示 如 果 这 个 套 接 
字 上 出 现 了 预期 的 网 络 事件 ， 则 希望 epoll 能 够 回调 它 的 handler 方 法 。 


套 接 字 


2) 用 生生 和 扑 站 人 性 


ngx_connection_t 结 构 


3) 将 连接 对 应 的 套 接 字 添加 到 


4 ) 调 用 connect 
方法 连接 上 游 服务 咒 


5 ) 设 置 连接 读 / 写 事件 
的 回调 方法 


6 ) 设 置 upstream 机 制 的 
write_event_ handler 方 法 


7) 设置 upstream 机 制 的 
read_event handle 访 法 


[检测 第 4 步 connect 的 返回 值 ] 
[连接 建立 成 功 ] 
[等 待 上 游 服务 器 的 返回 ] 


8) 将 连接 的 写 事件 
添加 到 定时 带 中 


9) 调用 ngx_http_upstream_send_request 
方法 发 送 请 求 


12-3 ngx_http_upstream_connect 方 法 的 流程 


4) 调用 connect 方 法 向 上 游 服务 器 发 起 TCP 连 接 ， 作 为 非 阻 塞 套 接 
字 ，connect 方 法 可 能 立刻 返回 连接 建立 成 功 ， 也 可 能 告诉 用 户 继 续 等 
计 上 游 服务 融 的 啊 应 ， 对 connect 和 连接 是 否 建立 成 功 的 检查 会 在 第 7 步 
后 进行 。 注 意 ， 这 里 并 没有 涉及 connect 返 回 失败 的 情形 ， 读 者 可 以 
考 第 11 章 中 这 种 系统 调用 失败 后 的 处 理 ， 本 章 不 会 讨论 细 玉 。 


ei 


人 


Sh 


5) 将 这 个 连接 ngx_connection_t 上 的 读 / 写 事件 的 handler 回 调 方 法 
都 设置 为 ngx_http_upstream_handler。 下 文 会 介绍 


ngx_http_upstream_handler 方 法 。 


6) 将 upstream 机 制 的 write_event_handler 方 法 设 为 
ngx_http_upstream_send_request_handler 。write_event_handler 和 
read_event_handler 的 用 法 参见 下 面 将 要 介绍 的 
ngx_http_upstream_handler 方 法 。 步骤 实际 上 决定 了 辐 上 游 服 务 器 
发 送 请 求 的 RE 8 


7) 设置 upstream 机 制 的 read_event_handler 方 法 为 
ngx_http_uUpstream_process_header， 也 就 是 由 
ngx_http_upstream_process_header 方 法 接收 上 游 服 务 絮 的 响应 。 


现在 开始 检查 在 第 4 步 中 调用 connect 方 法 连接 上 游 服 务 器 是 否 成 
功 ， 如 末 已 经 连接 成 功 ， 则 跳 到 第 9 步 执行 ， 如 采 尚 未 收 到 上 游 服 务 右 


连接 建立 成 功 的 应 答 ， 则 跳 到 第 8 步 执行 。 


8) 这 一 步 处 理 非 阻 塞 的 连接 尚未 成 功 建立 时 的 动作 。 实 际 上 ,在 
第 3 步 中 ， 套 接 字 已 经 加 入 到 epoll 中 监控 了 ， 因 此 ， 这 一 步 将 调用 
ngx_add_timer 方 法 把 写 事件 添 加 到 定时 器 中 ， 超 时 时 间 就 是 12.1.3 节 
中 介绍 的 ngx_http_upstream_conf t 结 构 体 中 的 connect_timeonut 成 员 ， 这 
是 在 设置 建立 TCP 连 接 的 超时 时 间 。 


9) 如 果 已 经 成 功 建立 连接 ， 则 调用 
ngx_http_upstream_send_request 方 法 向 上 游 服务 需 发 送 请 求 。 注 意 ， 在 
第 6 步 中 设置 的 发 送 请 求 方法 为 
ngx_http_upstream_send_request_handler， 它 与 
ngx_http_upstream_send_request 方 法 的 不 同 之 处 将 在 12.4 广 中 介绍 。 


以 上 的 第 5、 第 6、 第 7 步 都 与 ngx_http_upstream_handler 方 法 相 
关 ， 同 时 我 们 又 看 到 了 类 似 ngx_http_request_t 结 构 体 中 
write_event_ handler、read_event_handler 的 同名 方法 。 实 际 上 ， 


ngx_http_upstream_handler 方 法 与 图 11-7 展 示 的 ngx_http_request_handler 
方法 也 非常 相似 ， 下 面 看 看 它 到 底 做 了 些 什么 。 


static void ngx_http_upstream handler(ngx_event_t *ev) 


ngx_connection t *c; 
ngx_http_request_t *r,; 
ngx_http_upstream t *u; 
/* 由 事件 的 


data 成 员 取 得 


ngx_connection_t 连 接 。 注 意 ， 这 个 连接 并 不 是 
Nginx 与 客户 端的 连接 ， 而 是 


Nginx 与 上 游 服务 器 间 的 连接 


wh 
C = ev->data; 
// 由 连接 的 
data 成 员 取 得 


ngx_http_request_t 结 构 体 


r = c->data; 


/* 由 请 求 的 


upstream 成 员 取 得 表示 


upstream 机 制 的 
Ngx_http_upstream_t 结 构 体 
A 


U = r->upstream,; 
/* 注 意 ， 


ngx_http_request_t 结 构 体 中 的 这 个 


connection 连 接 是 客户 端 与 


Nginx 间 的 连接 


*/ 
Cc = r->connection; 
if (ev->write) 区 
/* 当 
Nginx 与 上 游 服 务 器 间 


TCP 连 接 的 可 写 事 件 被 触发 时 ， 


upstream 的 


write_event_handler 方 法 会 被 调 


*y 
U->write_event_handler(r, u); 
} else { 
/* 当 
Nginx 与 上 游 服务 器 间 


TCP 连 接 的 可 读 事件 被 触发 时 ， 


upstream 的 


read_event_handler 方 法 会 被 调 


6 


U->read_event_handler(r，U) 


} 
/*ngx_http_run_posted_requests 方 法 正 是 第 


11 章 图 


11-12 所 说 的 方法 。 注 意 ， 这 个 参数 


c 是 来 自 客户 端的 连接 ， 


post 请 求 的 执行 也 与 图 


11-12 完 全 一 致 


* 
/ 
ngx_http_run_posted_requests(c); 


其 实 ，ngx_http_upstream_handler 方 法 与 第 11 章 中 介绍 的 
ngx_http_request_handler 方 法 几乎 是 一 样 的 ， 它 们 的 最 后 一 步 都 是 调用 
相同 的 方法 执行 post 请 求 ， 区 别 只 是 前 者 将 调用 ngx_http_upstream_t 结 
构 体 中 的 读 写 回调 方法 ， 而 后 者 是 调用 ngx_http_request_t 结 构 体 中 的 
读 写 回调 方法 。 本 章 以 下 小 节 中 都 会 通过 ngx_http_upstream_t 结 构 体 中 
的 write_event_handler 和 read_event_handler， 设 置 与 上 游 之 间 对 应 的 读 / 
写 事件 出 现时 的 回调 方法 。 


12.4 发送 请 求 到 上 游 服 务 铅 


向 上 游 服 务 器 发 送 请 求 是 一 个 阶段 ， 因 为 请 求 的 大 小 是 未 知 的 ， 

所 以 发 送 请 求 的 方法 需要 被 epoll 调 度 许多 次 后 才 可 能 发 送 完 请 求 的 全 
部 内 容 。 在 图 12-3 中 的 第 6 步 将 ngx_http_upstream_t 里 的 
write_event_handler 成 员 设 为 ngx_http_upstream_send_request_handler 方 
法 ， 也 就 是 说 ， 由 该 方法 负责 反复 地 发 送 请 求 ， 可 是 ， 在 图 12-3 的 第 9 
步 又 直接 调用 了 ngx_http_upstream_send_request 方 法 发 送 请 求 ， 那 这 两 
种 方法 之 间 有 什么 关系 吗 ? 先 来 看 看 前 者 的 实现 ， 它 相对 简单 ， 这 里 
直接 列举 了 它 的 主要 源 代 码 ， 如 下 所 示 。 


static void ngx_http_upstream_send_request_handler(ngx_http_redquest_ tt *r, 
ngx_http_upstream_t *u) 


ngx_connection t *c,; 


// 获取 与 上 游 服 务 器 间 表 示 连 接 的 


ngx_connection_t 结 构 体 


c = U->peer.connection; 
// 写 事件 的 


timedout 标 志 位 为 


1 时 表示 向 上 游 服 务 器 发 送 的 请 求 已 经 超时 


if (c->write->timedout) { 
/* 将 超时 错误 传递 给 


ngx_http_upstream_next 方 法 ， 该 方法 将 会 根据 允许 的 错误 重 连 策 略 决定 : 重新 发 起 连接 执行 


upstream 请 求 ， 或 者 结束 


upstream 请 求 ， 详 见 


12 .9.2 节 


A 
ngx_http_upstream next(r, u, NGX_HTTP_UPSTREAM_FT_TIMEOUT); 
return; 


/*header_sent 标 志 位 为 


1 时 表明 上 游 服务 器 的 响应 需要 直接 转发 给 客户 端 ， 而 且 此 时 
Nginx 已 经 把 响应 包头 转发 给 客户 端 了 
*/ 


If (u->header_sent) { 
人 事实 上 ， 


header_sent 为 


1 时 一 定 是 已 经 解析 完全 部 的 上 游 响 应 包头 ， 并 且 开 始 向 下 游 发 送 


HTTP 的 包头 了 。 到 此 ， 是 不 应 该 继续 向 上 游 发 送 请 求 的 ， 所 以 把 


write_event_handler 设 为 任何 工作 都 没有 做 的 


ngx_http_upstream_dummy_handler 方 法 


U->write_event_handler = ngx_http_upstream dummy_handler; 
// 将 写 事件 添加 到 


epolli 中 


(void) ngx_handle write event(c->write, 0); 


// 因为 不 存在 继续 发 送 请 求 到 上 游 的 可 能 ， 所 以 直接 返回 


return; 


} 
// 调 


ngx_http_upstream_send_request 方 法 向 上 游 服务 器 发 送 请 求 


ngx_http_upstream send_request(r, u); 


可 见 ，ngx_http_upstream_send_request_handler 方 法 更 多 的 时 候 是 
在 检测 请 求 的 状态 ， 而 实际 负责 发 送 请 求 的 方法 是 
ngX_http_upstream_send_request， 图 12-4 列 出 了 
ngx_http_upstream_send_request 方 法 的 主要 执行 步骤 。 


下 面 说 明 以 上 8 个 步骤 的 意义 。 


1) 调用 ngx_output_ chain 方法 向 上 游 服务 器 发 送 
ngx_http_upstream_t 结 构 体 中 的 request_bufs 链 表 ， 这 个 方法 对 于 发 送 绥 
冲 区 构成 的 ngx_chain_t 链 表 非 常 有 用 ， 它 会 把 未 发 送 完成 的 链表 缓冲 
区 保存 下 来 ， 这 样 承 不 用 每 次 调用 时 都 携 市 上 request_bufs 链 表 。 怎 么 
理解 呢 ? 当 第 一 次 调用 ngx_output_chain 方 法 时 ， 需 要 传递 request_bufs 
链表 构成 的 请 求 ， 如 下 所 示 。 


rc = ngx_output_chain(&u->output, u->request_bufs); 


这 里 的 u 就 是 请 求 对 应 的 ngx_http_request_t 结 构 体 中 的 upstream 成 
员 (ngx_http_upstream_t 类 型 ， 如 果 ngx_output_chain 一 次 无 法 发 送 完 
所 有 的 request_bufs 请 求 内 容 ，ngx_output_chain_ctx_t 类 型 的 u->output 会 
把 未 发 送 完 的 请 求 剑 存 在 目 己 的 成 员 中 ， 同 时 返回 NGX_AGAIN 。 妆 
可 写 事件 再 次 触发 ， 发 送 请 求 时 就 不 需要 再 传递 参数 了 ， 例 如 : 


rc = ngx_output_chain(&u->output, NULL); 


为 了 标识 这 一 点 ，ngx_http_upstream _t 结 构 体 中 专门 有 一 个 标志 位 
request_sent 表 示 是 否 已 经 传递 了 request_bufs 缓 冲 区 。 因 此 ， 在 第 一 次 
以 request_bufs 作 为 参数 调用 ngx_output_chain 方 法 后 ，request_sent 会 置 
为 1 。 


2) 检测 写 事 件 的 timer_set 标 志 位 ，timer_set 为 1 时 表示 写 事件 仍然 
在 定时 絮 中 ， 那 么 这 一 步 首 先 把 写 事件 由 定时 兹 中 取出 ， 再 由 


ngx_output_chain 的 返回 值 决定 是 否 再 次 向 定时 器 中 加 入 写 事件 ， 那 时 


超时 时 间 也 会 重 置 。 


1 ) 发 送 缓冲 区 中 的 请 求 内 容 
到 上 游 服务 器 


2 ) 若 写 事件 在 定时 器 中 则 移 除 


[检测 第 1 步 中 ngx_output_chain 方 法 返回 值 ] 


[未 发 送 完 全 部 请 求 ] 


[已 发 送 完 全 部 请 求 , 准备 接收 响应 ] 
3) 将 写 事件 添 加 到 定时 器 中 


5 ) 将 读 事件 添加 到 定时 器 中 


[检测 读 事 件 的 ready 标 志 位 ] 4 ) 将 写 事件 添加 到 epoll 中 


过 


[ 暂 无 响应 可 读 ] 


[如 果 套 接 字 绥 冲 区 中 有 数据 可 读 ] 


6) 调用 ngx http _upstream_process_header 


方法 接收 响应 头 部 


8 ) 将 写 事件 添加 到 epoll 中 


©@ 


图 12-4 ”ngx_http_upstream_send_request 方 法 的 流程 图 


仿 测 ngx_output_chain 的 返回 值 ， 返 回 NGX_AGAIN 时 表示 还 有 请 
求 未 被 发 送 ， 此 时 跳 到 第 3 步 ， 如 果 返 回 NGX_OK， 则 表示 已 经 发 送 完 
全 部 请 求 ， 跳 到 第 5 步 执 行 。 


3) 调用 ngx_add_timer 方 法 将 写 事 件 添加 到 定时 器 中 ， 防 止 发 送 请 
求 超 时 。 超 时 时 间 束 是 ngx_http_upstream_conf_t 配 置 结构 体 的 


send timeout 成 员 。 


4) 调用 ngx_handle_write_event 方 法 将 写 事件 添加 到 epoll 中 ， 


ngx_http_upstream_send_request 方 法 结束 。 
5) 如 果 已 经 向 上 游 服 务 器 发 送 完 全 部 请 求 ， 这 时 将 准备 开始 处 理 


响应 ， 首 先 把 读 事件 添加 a 到 定时 器 中 检查 接收 响应 是 否 超 时 ， 超 时 时 
间 就 是 ngx_http_upstream_conf t 配 置 结构 体 的 read_timeout 成 员 。 


今 测 读 事件 的 ready 标 志 人 位， 如果 ready 为 1， 则 表示 已 经 有 啊 应 可 
以 读 出 ， 这 时 跳 到 第 6 步 执 行 ， 如 果 ready 为 0， 则 跳 到 第 7 步 执行 。 


6) 调用 ngx_http_upstream_process_header 方 法 接收 上 游 服 务 器 的 响 


儿 ， 在 12.5 节 中 会 详细 讨论 该 方法 。 


7) 如 果 暂 无 响应 可 读 ， 由 于 此 时 请 求 已 经 全 部 发 送 到 上 游 服 务 器 
了 ， 所 以 要 防止 可 写 事件 再 次 触发 而 又 调用 


ngx_http_upstream_send_request 方 法 。 这 时 ， 把 write_event_handler 设 为 


ngx_http_upstream_dummy_handler 方 法 ， 前 文 说 过 ， 该 方法 不 会 做 任何 
事情 。 这 样 即 使 与 上 游 间 的 TCP 连 接 上 再 次 有 可 写 事件 时 也 不 会 有 任何 
动作 发 生 ， 它 就 像 第 11 间 我 们 介绍 的 ngx_http_empty_handler 方 法 。 


8) 调用 ngx_handle_write_event 方 法 将 写 事件 加 入 到 epoll 中 。 


在 发 送 请 求 到 上 游 服务 右 的 这 个 阶段 中 ， 每 当 TCP 连 接 上 再 次 可 以 
发 类 字符 流 时 ， 虽 然 事 件 框架 束 会 回调 
ngx_http_upstream_send_request_handler 方 法 处 理 可 写 事 件 ， 但 最 终 还 
是 通过 调用 ngx_http_upstream_send_request 方 法 把 请 求 发 送出 去 的 。 


12.5 ”接收 上 洲 服 务 器 的 啊 应 头 部 


当 请 求全 部 发 送 给 上 游 服 务 絮 时 ，Nginx 开 始 准 备 接收 来 自 上 游 服 
务 器 的 响应 。 在 图 12-3 的 第 7 步 中 设置 了 由 
ngx_http_upstream_process_header 方 法 处 理 上 游 服 务 句 的 啊 应 ， 而 图 12- 
4 的 第 8 步 也 是 通过 调用 该 方法 接收 响应 的 ， 本 节 的 内 容 就 在 于 说 明 可 


能 会 被 反复 多 次 调用 的 ngx_http_upstream_process_header 方 法 。 


12.5.1 应 用 层 协议 的 两 段 划 分 方式 


在 12.1.1 市 我 们 已 经 了 解 到 ， 只 要 上 游 服 务 句 提供 的 应 用 层 协 议 是 
基于 TCP 实 现 的 ， 那 么 upstream 机 制 都 是 适用 的 。 基 于 TCP 的 啊 应 其 实 
就 是 有 顺序 的 数据 流 ， 那 么 ，upstream 机 制 只 需要 按照 接收 到 的 顺序 调 
用 HTTP 模 块 来 解析 数据 流 不 就 行 了 吗 ? 多 么 简单 和 清晰 ! 然而 ， 实 际 
上 ， 应 用 层 协 议 要 比 这 复杂 得 多 ， 这 主要 表现 在 协议 长 度 的 不 可 确定 
和 协议 内 容 的 解 机 上 。 首 先 ， 应 用 层 协议 的 响应 包 可 大 可 小 ， 如 最 小 
的 响应 可 能 只 有 128B， 最 大 的 响应 可 能 达到 5GB， 如 果 属 于 HTTP 框 染 
的 ngx_http_upstream_module 模 块 在 内 存 中 接收 到 全 部 响应 内 容 后 再 调 
用 各 个 HTTP 模 块 处 理 啊 应 ， 束 很 容易 引发 OutOfMemory 错 误 ， 即 使 没 
有 错误 也 会 因为 内 存 消耗 过 大 从 而 降低 了 并 发 处 理 能 力 。 如 果 在 磁 副 
文件 中 接收 全 部 响应 ， 又 会 带 来 大 量 的 磁盘 IO 操作 ， 最 终 大 幅 提高 服 


务 器 的 负载 。 其 次， 对 响应 中 的 所 有 内 容 都 进行 解析 并 无 从 要 (解析 
操作 毕竟 对 CPU 是 有 消耗 的 ) 。 例 如 ， 从 Memcached 服 务 器 上 下 载 一 幅 
图 片 ，Nginx 只 需要 解析 Memcached 协 议 ， 并 不 需要 解析 图 片 的 内 容 ， 
对 于 图 片 内 容 ，Nginx 只 需要 边 接收 边 转 发 给 客户 端 即 可 。 


为 了 解决 上 述 问 题 ， 应 用 层 协议 通常 都 会 将 请 求 和 响应 分 成 两 部 
分 : 包头 和 包 体 ， 其 中 包头 在 前 而 包 体 在 后 。 包 头 相 当 于 把 不 同 的 协 
议 包 之 间 的 共同 部 分 抽象 出 来 ， 不 同 的 数据 包 之 间 包 头 都 具备 相同 的 
格式 ， 服 务 器 必须 解析 包头 ， 而 包 体 则 完全 不 做 格式 上 的 要 求 ， 服 务 
如 是 否 解 析 它 将 视 业 务 上 的 需要 而 定 。 包 头 的 长 度 要 么 是 固定 大 小 ， 
要 么 是 限制 在 一 个 数值 以 内 〈 例 如 ， 类 似 Apache 这 样 的 Web 服务 器 默认 
情况 下 仅 接收 包头 小 于 4KB 的 HTTP 请 求 ) ， 而 包 体 的 长 度 则 非常 灵 
活 ， 可 以 非常 大 ， 也 可 以 为 0。 对 于 Nginx 服 务 器 来 说 ， 在 
process_header 处 理 包头 时 ， 需 要 开辟 的 内 存 大 小 只 要 能 够 容纳 包头 的 
长 度 上 限 即 可 ， 而 处 理 包 体 时 需要 开辟 的 内 存 大 小 情况 较 复杂 ， 可 参 
见 12.6 节 ~12.8-。 


包头 和 包 体 存储 什么 样 的 信息 完全 取决 于 应 用 层 协 议 ， 包 头 中 的 

时 通常 必须 包含 包 体 的 长 度 ， 这 是 应 用 层 协议 分 为 包头 、 包 体 两 部 
分 的 最 主要 原因 。 很 多 包头 还 会 包 舍 协议 有 版本、 请求 的 方法 类 型 、 数 
据 包 的 序列 号 等 信息 ， 这 些 是 upstream 机 制 并 不 关心 的 ， 它 已 经 在 
ngx_http_upstream_t 结 构 体 中 抽象 出 了 process_header 方 法 ， 由 具体 的 


HTTP 模 块 实现 的 process_header 来 解析 包头 。 实 际 上 ，upstream 机 制 并 
没有 对 HTTP 模 块 怎样 实现 process_header 方 法 进行 限制 ， 但 如 果 HTTP 
模块 的 日 的 是 实现 反 向 代理 ， 不 妨 将 接收 到 的 包头 按照 上 游 的 应 用 层 
协议 与 HITP 的 关系 ， 把 解析 出 的 一 些 头 部 适 配 到 ngx_http_upstream ft 
结构 体 中 的 headers_in 成 员 中 ， 这 样 ，upstream 机 制 在 图 12-5 的 第 8 步 驶 
会 自动 地 调用 ngx_http_upstream_process_headers 方 法 将 这 些 头 部 设置 到 
发 送 给 下 游客 户 病 的 HTTP 啊 应 包头 中 。 


包 体 的 内 容 往 往 较 为 简单 ， 当 HTTP 模块 希望 实现 反 向 代理 功能 时 
大 都 不 希望 解析 包 体 。 这 样 的 话 ，upstream 机 制 基于 这 种 最 常见 的 需 
求 ， 把 包 体 的 常见 处 理 方式 抽象 出 3 类 加 以 实现 ，12.5.2 市 中 将 介绍 这 3 
种 包 体 的 处 理 方式 。 


12.5.2 ”处 理 包 体 的 3 种 方式 


为 什么 upstream 机 制 不 是 仅仅 负责 接收 上 游 服 务 古 发 来 的 包 体 ， 再 
交 由 HTTP 模 块 决定 如 何 处 理 这 个 包 体 呢 ? 这 是 因为 upstream 有 一 个 最 
重要 的 使 命 要 完成 ! Nginx 作 为 一 个 试图 取代 Apache 的 Web 服 务 器 ， 最 
基本 的 反 向 代理 功能 是 必须 存在 的 ， 而 实现 反 向 代理 的 Web 服 务 器 并 不 
仅仅 和 希望 可 以 访问 上 游 服 务 器 ， 它 更 希望 upstream 能 够 实现 透 传 、 转 发 
上 游 响 应 的 功能 。 


upstream 机 制 不 关心 如 何 构造 发 送 到 上 六 的 请 求 内 容 ， 这 事实 上 是 
由 各 个 使 用 upstream 的 HTTP 模 块 实现 的 create_request 方 法 决定 的 ( 目 
前 的 HITP 反 向 代理 模块 是 这 么 做 的 : Nginx 将 客户 端的 请 求全 部 接收 
后 再 透 传 给 上 族 服 务 右 ， 这 种 方式 很 向 单 ， 又 对 减轻 上 游 服务 右 的 并 
发 负载 很 有 帮助 ) ， 但 对 响应 的 处 理 就 比较 复杂 了 ， 下 面 举 两 个 例子 
来 说 明 其 复杂 性 。 


如 采 Nginx 与 上 游 服 务 器 间 的 网 速 很 快 (例如 ， 两 者 都 在 一 个 机 房 
的 内 网 中 ， 或 者 两 者 间 拥 有 专线 ) ， 而 Nginx 与 下 游 的 客户 端 间 网 速 又 
很 慢 (例如 ， 下 游客 户 端 通过 公 网 访问 机 房 内 的 Nginx) ， 这 样 就 会 导 
致 Nginx 接 收 上 游 服 务 絮 的 啊 应 非常 快 ， 而 辣 下 游客 户 闹 转发 啊 应 时 很 
慢 ， 这 也 就 为 upstream 机 制 市 来 一 个 需求 :应 当 尽 可 能 地 把 上 游 服 务 器 
的 呆 应 接收 到 Nginx 服 务 髓 上 上， 包括 将 来 日 上 游 的 、 还 没 来 及 发 送 到 下 
游 的 包 体 缓存 到 内 存 中 ， 如 有 宁 使 用 的 内 存 过 大 ， 达 到 某 个 限制 国 值 
后 ， 为 了 降低 内 存 的 消耗 ， 还 需要 把 包 体 缓存 到 磁盘 文件 中 。 


如 果 Nginx 与 上 游 服 务 器 间 的 网 速 较 慢 (假设 是 公 网 线路 ) ， 而 
Nginx 与 下 游 的 客户 端 间 的 网 速 很 快 〈 例 如 ， 客 户 端 其 实 是 Nginx 所 在 
机 房 里 的 另 一 个 web 服务器 ) ， 这 时 就 不 存在 大 量 缓存 上 游 响 应 的 需求 
了 ， 完 全 可 以 开辟 一 块 固定 大 小 的 内 存 作为 缓冲 区 ， 一 边 接收 上 游 员 
应 ， 一边 向 下 游 转 发 。 每 当 向 下 游 成 功 转发 部 分 啊 应 后 就 可 以 复 用 绥 


冲 区 ， 这 样 既 不 会 消耗 大 量 内存 《增加 Nginx 并 发 量 ) ， 又 不 会 使 用 到 
人 磁 副 WO (减少 了 用 户 等 竺 响应 的 时 间 ) 。 


因此 ，upstream 机 制 提 供 了 3 种 处 理 包 体 的 方式 : 不 转发 响应 〈 即 
不 实现 反 向 代理 ) 、 转 发 响应 时 以 下 游 网 速 优先 、 转 发 响应 时 以 上 游 
网 速 优 和 完 。 怎 样 告诉 upstream 机 制 使 用 哪 种 方式 处 理 上 游 的 啊 应 包 体 
呢 ? 当 请 求 ngx_http_request_t 结 构 体 的 subrequest_in_memory 标 志 位 为 1 
时 ， 将 采用 第 1 种 方式 ， 即 不 转发 啊 应 ， 当 subrequest_in_memory 为 0 
时 ， 将 转发 响应 。 而 ngx_http_upstream_conf t 配 置 结构 体 中 的 buffering 
标志 位 ， 会 决定 转发 啊 应 时 是 否 开局 更 多 的 内 存 和 磁盘 文件 用 于 缓存 
上 游 啊 应 ， 如 果 buffering 为 0， 则 以 下 游 网 速 优先 ， 使 用 固定 大 小 的 内 
存 作为 缓存 ， 如 果 buffering 为 1， 则 以 上 游 网 速 优 先 ， 使 用 更 多 的 内 
人 存 、 便 副 文 件 作为 缓存 。 


1. 不 转发 啊 应 


不 转发 包 体 是 upstream 机 制 最 基本 的 功能 ， 特 别 是 客户 端 请 求 派生 
出 的 子 请 求 多 半 不 需要 转发 包 体 ，upstream 机 制 的 最 低 目 标 瓯 是 允许 
HTTP 模 块 以 TCP 访 问 上 游 服 务 器 ， 这 时 HTTP 模 块 仪 布 望 解析 包头 、 包 
体 ， 没 有 转发 上 游 响 应 的 需求 。upstream 机 制 提供 的 解析 包头 的 回调 方 
法 是 process_header， 而 解析 包 体 的 回调 方法 则 是 input_filter。 在 12.6 廊 
将 会 描述 这 种 处 理 包 体 的 最 基本 方式 是 如 何 工作 的 。 


2. 轩 发 啊 应 时 下 游 网 速 优 先 


在 转发 啊 应 时 ， 如 果 下 游 网 速 快 于 上 游 网 速 ， 或 者 它们 速度 相差 
不 大 ， 这 时 不 需要 开辟 大 块 内 存 或 者 磁盘 文件 来 缓存 上 游 的 响应 。 我 
们 将 在 12.7 节 中 讲述 这 种 处 理 方式 下 upstream 机 制 是 如 何 工 作 的 。 


3. 转 发 啊 应 时 上 游 网 速 优 移 


在 转发 啊 应 时 ， 如 果 上 游 网 速 快 于 下 游 网 速 (由 于 Nginx 文 持 高 并 
发 怪 性 ， 所 以 大 多 数 时 候 部 用 于 做 最 前 剖 的 Web 上 服务 大， 这 时 上 游 网 速 
都 会 快 于 下 游 网 速 ) ， 这 时 和 需要 开辟 内 存 或 者 磁盘 文件 缓存 来 自 上 游 
服务 器 的 啊 应 ， 注 意 ， 缓 存 可 能 会 非常 大 。 这 种 处 理 方式 比较 复杂 ， 
在 12.8 节 中 我 们 会 详细 描述 其 主要 流程 。 


12.5.3 ”接收 啊 应 头 部 的 流程 


下 面 开 始 介绍 读 取 上 游 服 务 右 啊 应 的 
ngx_http_upstream_process_header 方 法 ， 这 个 方法 主要 用 于 接收 、 解 析 
响应 头 部 ， 当 然 ， 由 于 upstream 机 制 是 不 涉及 应 用 层 协议 的 ， 谁 使 用 了 
upstream 谁 就 要 负责 解析 应 用 层 协议 ， 所 以 必须 由 HTTP 模 块 实现 的 
process_header 方 法 解析 啊 应 包头 。 当 包头 接收 、 解析 完毕 后 ， 
ngx_http_upstream_process_header 方 法 还 会 决定 以 哪 种 方式 处 理 包 体 

(参见 12.5.2 市 中 介绍 的 3 种 包 体 处 理 方式 ) 。 


在 接收 响应 包头 的 阶段 中 ， 处 理 连 接 读 事件 的 方法 始终 是 
ngx_http_upstream_process_header， 也 就 是 说 ， 该 方法 会 反复 被 调用 ， 
在 人 研究 其 流程 时 需要 特别 注意 。 图 12-5 描 述 了 它 的 主要 流程 。 


1) 检查 读 事 件 
的 有 效 性 
[接收 响应 超时 或 者 还 未 发 送 请 求 给 上 游 ] 


[ 读 事 件 可 用 , 再 检查 buffer 接收 缓冲 区 是 否 可 用 |] 


2) 调 用 ngx_http_ upstream_next 
方法 重 试 或 结 


[如 果 buffer 组 冲 区 未 分 配 ] 


多 x 1 人 肝癌 
[缓冲 区 | 
Hi 


4) 调 用 recv 
方法 读 取 缓冲 区 
[检查 recv 返 回 值 ] 


[连接 关闭 


或 者 错误 ] 


[返回 NGX_AGAIN] 


[buffer 绥 冲 区 用 尽 ] 
[返回 NGX_HTTP_UPSTREAM_INVALID_HEADERI 


[ 读 取 到 响应 ] 


6) 调 用 process_header 
方法 解析 响应 包头 
冲 区 ] [检查 process header 返回 值 ] 


5 ) 将 读 事 件 
3 | [返回 NGX_ERRORI] 添加 到 epoll 中 


[返回 NGX_AGAN 后 ， 表 检查 buffer 是 否 全 部 用 尽 ] 
[返回 Ncx on 


[有 空闲 级 


7) 调 用 ngx_http_upstream_finalize_request 
方法 结束 请 求 


8) 调用 ngx_http_upstream_process_headers 
方法 处 理 headers_in 
[检测 subrequest in_ memory 标志 位 ,确认 是 否 需 要 转 发 包 体 ] 


subrequest_in_memory 为 0] 9) 调 用 ngx_http_upstream_send_response 


方法 转发 响应 


[subrequestLin_memory 为 1, 不 转发 响应 ] 


0 


[检测 buffer 中 是 否 已 经 接收 到 包 体 ] 
dbuffer 中 已 含有 包 体 ] 


肖 用 input_filter 
方法 处 理 已 接收 到 的 包 体 
[buffer 中 未 含有 包 体 ] 


12) 重新 设置 
read_event_ handler 


es ten process_body_in_memory @® 


理 包 体 


图 12-5 ngx_http_upstream_process_header 方 法 的 流程 图 


下 面 详细 介 绍 图 12-5 中 的 13 个 步骤 。 


1) 首先 检查 读 事件 是 否 有 效 ， 包 括 检查 timedout 标 志 位 是 否 为 1， 
如 采 timedout 为 1， 则 表示 读 取 响应 已 经 超时 ， 这 时 跳 到 第 2 步调 用 
ngx_http_upstream_next 方 法 决定 下 一 步 的 动作 ， 其 中 传递 的 参数 是 
NGX_HTTP_UPSTREAM_FT_TIMEOUT。 如果 timedout 为 0， 则 继续 检 
查 request_sent 标 志 位 。 如 果 request_sent 为 0， 则 表示 还 没有 发 送 请 求 到 
上 游 服 务 右 就 收 到 来 自 上 游 的 啊 应 ， 不 符合 upstream 的 设计 场景 ， 这 时 
仍然 跳 到 第 2 步调 用 ngx_http_upstream_next 方 法 ， 传 递 的 参数 是 
NGX_HTTP_UPSTREAM_FT_ERROR。 如果 读 事件 完 全 有 效 ， 则 跳 到 


第 3 步 执 行 。 


2) 只 有 请 求 触发 了 失败 条 件 后 ， 才 会 执行 hgx_http_upstream_next 
方法 ， 该 方法 将 会 根据 配置 信息 决定 下 一 步 究 竟 是 重新 发 起 upstream 请 
求 ， 还 是 结束 当前 请 求 ， 在 12.9.2 世 会 详细 说 明 该 方法 的 工作 流程 。 当 
前 读 事 件 处 理 完 毕 。 


3) 检查 ngx_http_upstream_t 结 构 体 中 接收 响应 头 部 的 buffer 绥 冲 
区 ， 如 果 它 的 start 成 员 指 向 NULL， 说 明 缓冲 区 还 未 分 配 内 存 ， 这 时 将 
按照 ngx_http_upstream_conf t 配 置 结构 体 中 的 buffer_size 成 员 指定 的 大 
小 来 为 buffer 缓 种 区 分 配 内 存 。 


4) 调用 recv 方 法 在 buffer 缓 冲 区 中 读 取 上 游 服 务 器 发 来 的 啊 应 。 检 
测 recv 方 法 的 返回 值 ， 有 3 类 返回 值 会 导致 3 种 不 同 的 结果 : 如 果 返 回 
NGX_AGAIN， 则 表示 还 需要 继续 接收 啊 应 ， 这 时 跳 到 第 5 步 执行 ， 如 


果 返 回 0 (表示 上 游 服 务 器 主动 关闭 连接 ) 或 者 返回 NGX_ERROR， 这 
时 跳 到 第 2 步 执行 ngx_http_upstream_next 方 法 ， 传 递 的 参数 是 
NGX_HTTP_UPSTREAM_FT_ERROR; 如 果 返 回 正 数 ， 这 时 该 数值 表 
示 接 收 到 的 响应 长 度 ， 路 到 第 6 步 处 理 响应 。 


5) 调用 ngx_handle_read_event 方 法 将 读 事件 再 添加 到 epoll 中 ， 等 
待 读 事件 的 下 次 触发 。ngx_http_upstream_process_header 方 法 执行 完 


毕 。 


6) 调用 HTTP 模 块 实现 的 process_header 方 法 解析 响应 头 部 ， 检 测 
其 返回 值 : 返回 NGX_HTTP_UPSTREAM_INVALID_HEADER 表 示 包 
头 不 合法 ， 这 时 跳 到 第 2 步调 用 ngx_http_upstream_next 方 法 ， 传 递 的 参 
数 是 NGX_HTTP_UPSTREAM_FT_INVALID_HEADER; 返回 
NGX_ERROR 表 示 出 现 错误 ， 直 接 跳 到 第 7 步 执 行 ， 返 回 NGX_OK 表 示 
解析 到 完整 的 包头 ， 这 时 跳 到 第 8 步 执 行 ， 返回 NGX_AGAIN 表 示 包 头 
还 没有 接收 完整 ， 这 时 将 检测 buffer 缓 冲 区 是 否 用 尽 ， 如 果 缓 冲 区 已 经 
用 尽 ， 则 说 明 包 头 太 大 了 ， 超 出 了 缓冲 区 允许 的 大 小 ， 这 时 跳 到 第 2 步 
调用 ngx_http_upstream_next 方 法 ， 传 递 的 参数 依然 是 
NGX_HTTP_UPSTREAM_FT_INVALID_HEADER， 其 表示 包头 不 合 
法 ， 而 如 果 绥 冲 区 还 有 空 闪 空间 ， 则 返回 第 4 步 继 续 接 收 上 游 服务 颖 的 
响应 。 


7) 调用 ngx_http_upstream_finalize_request 方 法 结束 请 求 〈 详 见 


12.9.3 人 ) ，ngx_http_upstream_process_header 方 法 执行 完毕 。 


8) 调用 ngx_http_upstream_process_headers 方 法 处 理 已 经 解析 出 的 
头 部 ， 该 方法 将 会 把 已 经 解析 出 的 头 部 设置 到 请 求 ngx_http_request_t 结 
构 体 的 headers_out 成 员 中 ， 这 样 在 调用 ngx_http_send_header 方 法 发 送 啊 
应 包头 给 客户 端 时 将 会 发 送 这 些 设置 了 的 头 部 。 


接 下 来 检查 是 否 需 要 转发 响应 ，ngx_http_request_t 结 构 体 中 的 
subrequest_in_memory 标 志 位 为 1 时 表示 不 需要 转发 啊 应 ， 跳 到 第 10 步 
执行 ，subrequest_in_memory 为 0 时 表示 需要 转发 响应 到 客户 端 ， 跳 到 


第 9 步 执 行 。 


9) 调用 ngx_http_upstream_send_response 方 法 开始 转发 响应 给 客户 


端 ， 同 时 ngx_http_upstream_process_header 方 法 执行 完毕 。 


10) 首先 检查 HITP 模 块 是 否 实现 了 用 于 处 理 包 体 的 input_filter 方 
法 ， 如 有 果 没 有 实现 ， 则 使 用 upstream 定 义 的 默认 方法 
ngx_http_upstream_non_buffered_filter 代 替 input_filter， 其 中 
input_filter_ctx 将 会 被 设置 为 ngx_http_request_t 结 构 体 的 指针 。 如 果 用 
户 已 经 实现 了 input_filter 方 法 ， 则 表示 用 户 和 希望 自 己 处 理 包 体 (如 
ngx_http_memcached_module 模 块 ) ， 这 时 首先 调用 input_filter_init 方 法 
为 处 理 包 体 做 初始 化 工作 。 


11) 在 第 6 步 的 process_header 方 法 中 ， 如 果 解 析 完 包头 后 缓冲 区 中 
还 有 多 余 的 字符 ， 则 表示 还 接收 到 了 包 体 ， 这 时 将 调用 input_filter 方 法 
第 一 次 处 理 接收 到 的 包 体 。 


12) 设置 upstream 的 read_event_handler 为 
ngx_http_upstream_process_body_in_memory 方 法 ， 这 也 表示 再 有 上 游 服 
务 器 发 来 响应 包 体 ， 将 由 该 方法 来 处 理 (参见 12.6 节 ) 。 


13) 调用 ngx_http_upstream_process_body_in_memory 方 法 开始 处 理 
包 体 。 


从 上 面 的 第 12 步 可 以 看 出 ， 当 不 需要 转发 响应 时 ， 
ngx_http_upstream_process_body_in_memory 方 法 将 作为 读 取 上 游 服 务 器 
包 体 的 回调 方法 。 什 么 时 候 无 须 转发 包 体 呢 ? 在 subrequest_in_memory 
标志 位 为 1 时 ， 实 际 上 ， 这 也 意味 着 当前 请 求 是 个 subrequest 子 请 求 。 也 
束 是 说 ， 在 通 间 情况 下 ， 如 末 来 目 客户 端 的 请 求 直接 使 用 upstream 机 
制 ， 那 都 需要 将 上 游 服 务 器 的 响应 直接 转发 给 客户 端 ， 而 如 果 是 客户 
问 请 求 派 生出 的 子 请 求 ， 则 不 需要 转发 上 游 的 响应 。 因 此 ， 当 我 们 开 
发 HTTP 模 块 实现 某 个 功能 时 ， 若 需要 访问 上 游 服 务 絮 获取 一 些 数据 ， 
那么 可 开发 两 个 HTTP 模块 ， 第 一 个 HTTP 模 块 用 于 处 理 客户 端 请 求 ， 

当 它 需要 访问 上 游 服务 器 时 束 派 生出 子 请 求 访问 ， 第 二 个 HITP 模 块 则 
专用 于 访问 上 游 服 务 器 ， 在 子 请 求解 析 完 上 游 服务 器 的 响应 后 ， 再 激 
活 父 请 求 处 理 客 户 病 要 求 的 业务 。 


@ 注意。 以 上 描述 的 开发 场景 是 Nginx 推 荐 用 户 使 用 的 方式 ， 虽 
然 可 以 通过 任意 地 修改 subrequest 标 志 位 来 更 改 以 上 特性 ， 但 目前 这 种 
设计 对 于 分 离 关注 点 还 是 非常 有 效 的 ， 是 一 种 很 好 的 设计 模式 ， 如 无 
必要 最 好 不 要 更 改 。 


从 上 面 的 第 9 步 可 以 看 出 ， 当 需要 转发 包 体 时 将 调用 
ngx_http_upstream_send_response 方 法 来 转发 包 体 。 
ngx_http_upstream_send_response 方 法 将 会 根据 ngx_http_upstream_conf + 
配置 结构 体 中 的 buffering 标 志 位 来 决定 是 否 打 开 绥 存 来 处 理 啊 应 ， 也 就 
是 说 ，buffering 为 0 时 通常 会 黑 认 下 游 网 速 更 快 ， 这 时 不 需要 缓存 响应 
(在 12.7 节 中 将 会 介绍 这 一 流程 ) 。 如 果 buffering 为 1， 则 表示 上 游 网 
速 更 快 ， 这 时 需要 用 大 量 内 存 、 磁 盘 文 件 来 缓存 来 自 上 游 的 啊 应 (在 


12.8 节 中 会 介绍 这 一 流程 ) 。 


12.6 不 转发 啊 应 时 的 处 理 流程 


实际 上 ， 这 里 的 不 转发 啊 应 只 是 不 使 用 upstream 机 制 的 转发 啊 应 功 
能 而 已 ， 但 如 果 HTTP 模 块 有 意愿 转发 响应 到 下 游 ， 还 是 可 以 通过 
input_filter 方 法 实现 相关 功能 的 。 


当 请 求 属于 subrequest 子 请 求 ， 且 要 求 在 内 存 中 人 处理 包 体 时 (在 第 5 
章 介 绍 过 ngx_http_subrequest 方 法 ， 通 过 它 派 生子 请 求 时 ， 可 以 将 最 后 
一 个 flag 参 数 设置 为 NGX_HTTP_SUBREQUEST_IN_MEMORY 宏 ， 这 
样 束 将 ngx_http_request_t 结 构 体 中 的 subrequest_in_memory 标 志 位 设 为 1 
了 ) ， 束 会 进入 本 节 摘 述 的 不 转发 响应 这 个 流程 。 或 者 通过 主动 设置 
subrequest_in_memory 标 志 位 为 1 也 可 以 做 到 ， 当 然 并 不 推荐 这 样 做 。 
为 什么 昵 ?因为 不 需要 转发 响应 时 的 应 用 场景 通常 如 下 : 业务 需求 导 
致 需要 综合 上 游 服 务 器 的 数据 来 重新 构造 发 往 客户 端的 啊 应 ， 如 从 上 
族 的 数据 库 或 者 Tomcat 服 务 器 中 获取 用 户 权限 信息 等 。 这 时 ， 根 据 
Nginx 推 荐 的 设计 模式 ， 应 当 由 原始 请 求 处 理 客户 端的 请 求 ， 并 派生 出 
子 请 求 访问 上 游 服 务 侨 ， 在 这 种 场景 下 ， 一 般 会 希望 在 内 存 中 解析 上 
族 服 务 磺 的 啊 应 。 


人 注意。 其 实 ， 在 内 存 中 处 理 上 游 响 应 的 包 体 也 有 两 种 方式 ， 
第 一 种 方式 接收 到 全 部 的 包 体 后 再 开始 处 理 ， 第 二 种 方式 是 每 接收 到 


一 部 分 啊 应 后 殊 处 理 这 一 部 分 。 第 一 种 方式 可 能 浪费 大 量 内 存 用 于 接 
收 完整 的 啊 应 包 体 ， 第 二 种 方式 则 会 始终 复 用 同一 块 内 存 绥 促 区 。 
HTTP 模 块 可 以 自由 地 选择 使 用 哪 种 方式 。 


ngx_http_upstream_process_body_in_memory 就 是 在 upstream 机 制 不 
转发 啊 应 时 ， 作 为 读 事 件 的 回调 方法 在 内 存 中 人 处 理 上 游 服 务 器 响应 包 
体 的 。 每 次 与 上 游 的 TCP 连 接 上 有 读 事件 触发 时 ， 它 都 会 被 调用 ， 
HTTP 模 块 通过 重新 实现 input_filter 方 法 来 处 理 包 体 ， 在 12.6.1 节 中 会 讨 
论 如 何 实现 这 个 回调 方法 ， 如 果 HTTP 模 块 不 实现 input_filter 方 法 ， 那 
么 upstream 机 制 就 会 自动 使 用 默认 的 
ngx_http_upstream_non_buffered filter 方法 来 处 理 包 体 ， 在 12.6.2 节 中 会 
讨论 这 个 默认 的 input_filter 方 法 做 了 些 什 么 ;在 12.6.3 节 中 将 会 具体 分 


析 ngx_http_upstream_process_body_in_memory 方 法 的 工作 流程 。 


12.6.1 input_filter 方 法 的 设计 


先 来 看 一 下 input_filter 回 调 方法 的 定义 ， 如 下 所 示 。 


ngx_int_t (*input_filter)(void *data, ssize t bytes ) ， 


其 中 ，bytes 参 数 吓 本 次 接收 到 的 包 体 长 度 。 而 data 参 数 却 不 是 指 癌 
接收 到 的 包 体 的 ， 它 实际 上 是 在 局 动 upstream 机 制 之 前 ， 所 设置 的 


ngx_http_upstream_t 结 构 体 中 的 input_filter_ctx 成 员 ， 下 面 看 一 下 它 的 定 
义 o 


void *input_filter_ctx; 


它 被 设计 为 可 以 指向 任意 结构 体 ， 其 实 就 是 用 来 传递 参数 的 。 
为 在 内 存 中 处 理 包 体 时 ， 可 能 需要 一 个 结构 体 作 为 上 下 文 存储 状态 、 
结果 等 一 些 信 息 ， 这 个 结构 体 必 须 在 启动 upstream 机 制 前 设置 。 同 时 ， 
在 处 理 包 体 前 ， 还 会 调用 一 次 input_filter_init 方 法 (HTTP 模 块 如 果 需 要 
在 开始 接收 包 体 时 初始 化 变量 ， 都 会 在 这 个 方法 中 实现 ) ， 下 面 看 一 
下 它 的 定义 。 


ngx_int_t (*input_filter_init)(void *data); 


data 参 数 意义 同上 ， 仍 然 是 input_filter_ctx 成 员 。 


下 面 将 重点 讨论 如 何在 input_filter 方 法 中 处 理 包 体 。 首 先 要 和 弄 清楚 
是 从 哪里 获取 到 本 次 接收 到 的 上 游 响应 包 体 。 答 案 是 可 由 ngx_buf t 类 
型 的 buffer 绥 冲 区 获得 。buffer 绥 冲 区 中 的 last 成 员 指 癌 本 次 接收 到 的 包 
体 的 起 始 地 址 ， 而 input_filter 方 法 的 bytes 参 数 表 明了 本 次 接收 到 包 体 的 
字 节 数 。 通 过 buffer->last 和 bytes 获 取 到 本 次 接收 到 的 包 体 后 ， 下 面 的 工 
作 就 是 由 HTTP 模 块 处 理 接 收 到 的 包 体 。 


在 处 理 完 这 一 次 收 到 的 包 体 后 ， 需 要 告诉 buffer 绥 冲 区 已 经 处 理 过 
刚 接收 到 的 包 体 吗 ? 这 束 需 要 看 业务 需求 了 。 


如 有 果 我 们 需要 反复 使 用 buffer 缓 冲 区 ， 即 buffer 指 向 的 这 块 内 存 需 要 
复 用 ,或 者 换 句 话说 ， 下 次 接收 到 的 啊 应 将 会 禾 盖 buffer 上 刚刚 接收 到 
的 了 啊 应 ， 那 么 input_filter 方 法 被 调用 时 必须 处 理 完 buffer 绥 冲 区 中 的 全 
部 内 容 ， 这 种 情况 下 不 需要 修改 buffer 缓 冲 区 中 的 成 员 。 当 再 次 接收 到 
后 续 的 包 体 时 ， 将 会 继续 从 buffer->last 指 向 的 内 存 地 址 处 覆盖 上 次 的 包 
体内 容 。 


如 采 我 们 硕 望 buffer 缓 冲 区 保存 部 分 或 者 全 部 的 包 体 ， 则 需要 进行 
针对 性 的 处 理 。 我 们 知道 ， 在 ngx_buf t 表 示 的 缓冲 区 中 ，start 和 end 成 
员 圈 定 了 缓冲 区 的 可 用 内 存 ， 这 对 于 buffer 缓 冲 区 来 说 同样 成 立 ，last 成 
员 将 指 癌 接收 到 的 上 游 服务 大 的 啊 应 包 体 的 起 始 内 存 地 址 。 因 此 ， 目 
由 地 移动 last 指 针 就 古 在 改变 buffer 绥 冲 区 。 例 如 ， 如 果 和 希望 buffer 绥 冲 
区 存储 全 部 包 体内 容 ， 那 么 不 妨 把 last 指 针 间 后 移动 bytes 字 节 (参见 
12.6.2 节 ) ; 如 果 希 望 buffer 绥 冲 区 尽 可 能 地 接收 包 体 ， 等 缓冲 区 满 后 
再 从 头 接收 ， 那 么 可 以 检测 last 指 针 ， 在 last 未 达到 end 指 针 的 位 置 时 可 
以 继续 癌 后 移动 ， 直 到 last 到 达 end 指 针 处 ， 在 到 达 end 指 针 后 可 以 把 last 
指针 指 同 start 成 员 ， 这 样 又 会 重头 复 用 这 块 内 存 了 。 


input_filter 的 返回 值 非常 简单 ， 只 要 不 是 返回 NGX_ERROR， 就 都 
认为 是 成 功 的 ， 当 然 ， 不 出 错时 最 好 还 是 返回 NGX_OK。 如 果 返 回 


NGX_ERROR， 则 请 求 会 结束 ， 人 参见 图 12-6。 


12.6.2 ”默认 的 input_filter 方 法 


如 果 HTTP 模 块 没 有 实现 input_filter 方 法 ， 那 么 将 使 用 
ngx_http_upstream_non_buffered_filter 方 法 作为 input_filter， 这 个 默认 的 
方法 将 会 试图 在 buffer 绥 冲 区 中 存放 全 部 的 啊 应 包 体 。 


ngx_http_upstream_non_buffered_filter 方 法 其 实 很 倘 单 ， 下 面 直接 
列 出 其 主要 代码 来 分 析 该 方法 。 


static ngx_int _t ngx_http_upstream non_buffered filter(void *data，Ssize_t bytes) 


/* 前 文 说 过 ， 


data 参 数 就 是 


ngx_http_upstream_t 结 构 体 中 的 


input_filter_ctx， 当 


HTTP 模 块 未 实现 
input_filter 方 法 时 ， 
input_filter_ctx 成 员 会 指向 请 求 的 
ngx_http_request_t 结 构 体 


*/ 
ngx_http_request t *r = data; 
ngx_buf_t *b; 
ngx_chain_t *cl, **]]; 
ngx_http_upstream t *u; 
U = r->upstream,; 


/* 找 到 


out_bufs 链 表 的 末尾 ， 其 中 


cl 指向 链表 中 最 后 一 个 
ngx_chain_t 元 素 的 


next 成 员 ， 所 以 


cl 最 后 一 定 是 
NULL 空 指针 ， 而 


11 指 向 最 后 一 个 缓冲 区 的 地 址 ， 它 用 来 在 后 面 的 代码 中 向 


xl 


out_bufs 链 表 添 加 新 的 缓冲 
WA 
for (cl = u->out_bufs, 11 = &u->out_bufs; cl; cl = cl->next) 
L 11 = &cl->next; 
pr buen 的 
ngx_buf_t 结 构 体 构成 的 链表 ， 如 果 
free_bufs 此 时 是 空 的 ， 那么 将 会 重新 
r->poo1 内 存 池 中 分 配 一 个 


ngx_buf_t 结 构 体 给 


cl1; 如 果 
free_bufs 链 表 不 为 空 ， 则 直接 由 


free_bufs 中 获取 一 个 


ngx_buf_t 结 构 体 给 
cl*/ 
cl = ngx_chain_ get_ free buf(r->pool, &u->free_bufs); 
if (cl == NULL) { 
return NGX_ERROR 
} 
// 将 新 分 配 的 


ngx_buf_t 结 构 体 添加 到 


out_bufs 链 表 的 末尾 


*]1 = cil; 
/* 修 改 新 分 配 缓冲 区 的 标志 位 ， 表 明 在 内 存 中 ， 


flush 标 志 位 为 可 能 发 送 缓冲 区 到 客户 端 服务 ， 参 见 


12 .7 节 


5 多 
cl->buf->flush = 1; 
cl->buf->memory = 1; 


// buffer 缓 冲 区 才 是 真正 接收 上 游 服务 器 响应 包 体 的 缓冲 区 


区 


b = &u->buffer ; 
// 1Last 实 际 指向 本 次 接收 到 的 包 体 首 地 址 


cl->buf->pos = b->last; 


// last 向 后 移动 
bytes 字 节 ， 意 味 着 
buffer 需 要 保存 这 次 收 到 的 包 体 

b->last += bytes; 

// last 和 
pos 成 员 确定 了 
out_bufs 链 表 中 每 个 缓冲 区 的 包 体 数 据 


cl->buf->last = b->last,; 
cl->buf->tag = u->output.tag; 
/* 如 果 没 有 设置 包 体 长 度 ， 


u->length 就 是 


NGX_MAX_SIZE_T_VALUE， 那 么 到 这 里 结束 


*/ 
if (u->length == NGX_MAX_SIZE T_VALUE) { 
return NGX_OK; 


// 更 新 


length， 需 要 接收 到 的 包 体 长 度 减少 


bytes 字 节 


U->Jlength -= bytes; 
return NGX_OK， 


可 以 看 人 到， 默认 的 input_filter 方 法 会 试图 让 独立 的 buffer 绥 冲 区 保 
存 全 部 的 包 体 ， 这 就 要 求 我 们 对 上 游 服 务 器 的 响应 包 体 大 小 有 绝对 正 
确 的 判断 ， 否 则 一 旦 上 游 服务 器 发 来 的 响应 包 体 超过 buffer 绥 冲 区 的 大 


小 ， 请 求 将 会 出 错 。 


@ 注音 ”对 于 上 述 这 段 代码 的 理解 ， 可 参见 图 12.8 第 4 步 中 
ngx_chain_update_chains 方 法 的 执行 过 程 ， 它 们 是 配对 执行 的 。 


12.6.3 ”接收 包 体 的 流程 


实现 的 input_filter 方 法 处 理 包 体 ， 如 图 12-6 所 示 。 
下 面 分 析 图 12-6， 了 解 一 下 在 内 存 中 人 处理 包 体 的 流程 。 


1) 首先 要 检查 Nginx 接 收 上 游 服 务 器 的 响应 是 否 超 时 ， 也 就 是 检 
查 读 事件 的 timedout 标 志 位 。 如 果 timedout 为 1， 则 表示 读 取 啊 应 超时 ， 
这 时 跳 到 第 2 步调 用 ngx_http_upstream_finalize_request 方 法 结束 请 求 ， 
传递 的 参数 是 NGX_ETIMEDOUT ( 详 见 12.9.3 节 ) ; 如 果 timedout 为 
0， 则 继续 执行 第 3 步 。 


2) 调用 ngx_http_upstream_finalize_request 方 法 结束 请 求 ， 该 方法 
类 似 于 ngx_http_finalize_request 方 法 ， 它 们 都 需要 一 个 rc 参数 ， 来 决定 
该 方法 的 行为 。 


3) 在 保存 着 响应 包 体 的 buffer 缓 冲 区 中 ，last 成 员 指向 空闲 内 存 块 
的 地 址 (下 次 还 会 由 last 处 开始 接收 响应 包 体 ) ， 而 end 成 员 指 向 缓冲 区 
的 结尾 ， 用 end-last 即 可 计算 出 剩余 空 内 内存。 如 果 缓 冲 区 全 部 用 尽 ， 
则 跳 到 第 2 步调 用 ngx_http_upstream_finalize_request 方 法 结束 请 求 ， 如 
有 果 还 有 空 采 缓冲 区 ， 则 跳 到 第 4 步 接收 包 体 。 


4) 调用 recv 方 法 接收 上 游 服 务 器 的 响应 ， 接 收 到 的 内 容 存放 在 
buffer 绥 冲 区 的 last 成 员 指 同 的 内 存 中 。 检 查 recv 的 返回 值 ， 不 同 的 返回 
值 会 导致 3 种 结果 : 如 果 返 回 NGX_AGAIN， 则 表示 期 待 下 一 次 的 读 事 
件 ， 这 时 跳 到 第 6 步 执行 ， 如 果 返 回 NGX_ERROR 或 者 上 游 服 务 器 主动 
关闭 连接 ， 则 跳 到 第 2 步 结 束 请 求 ， 如果 返 回 正 数 ， 则 表示 接收 到 的 响 
应 长 度 ， 这 时 跳 到 第 5 步 处 理 包 体 。 


5) 调用 HTTP 模 块 实现 的 input_filter 方 法 处 理 本 次 接收 到 的 包 体 。 
仿 测 input_filter 方 法 的 返回 值 ， 返 回 NGX_ERROR 时 跳 到 第 2 步 结束 请 
求 。 否 则 ， 再 检测 读 事件 的 ready 标 志 人 位， 如果 ready 为 1， 则 表示 仍 有 
TCP 流 可 以 读 取 ， 这 时 跳 到 第 3 步 执行 ， 如果 ready 为 0， 则 路 到 第 6 步 执 


一 


休 。 
6) 调用 ngx_handle_read_event 方 法 将 读 事件 添加 到 epoll 中 。 


7) 调用 ngx_add_timer 方 法 将 读 事件 添加 到 定时 器 中 ， 超 时 时 间 为 
ngx_http_upstream_conf t 配 置 结构 体 中 的 read_timeout 成 员 。 


在 内 存 中 处 理 包 体 的 关键 在 于 如 何 实 现 input_filter 方 法 ， 特 别 十 在 
该 方法 中 对 buffer 绥 冲 区 的 管理 。 如 琳 上 游 服 务 句 的 啊 应 包 体 非常 小 ， 
可 以 考虑 本 节 说 明 的 这 种 方式 ， 它 的 效率 很 高 。 


1 ) 检查 读 事件 
是 否 超 时 
[检查 读 事件 的 timedout 标 志 位 ] 


[timedout 为 1] 


[timedout 为 0] 


3) 计算 剩余 空 
闲 缓冲 区 
[buffer 中 是 和 否 还 有 空闲 缓冲 区 ] 


[buffer 缓 冲 区 用 尽 ] 
[buffer 缓 冲 区 还 有 空闲 空间 ] 
4) 使 用 ree 访 法 读 取 上 游 服 务 央 


发 来 的 包 体 
[检测 recv 返 回 值 | 


E 接 字 本 流 可 读 
[区 梳子 上 作 有 有 流 了 训 ] [出 错 或 者 上 游 服务 器 关闭 了 连接 ] 


[接收 到 包 体 ] 
[返回 NGX_AGAIN] 5 ) 调 用 input filter 
方法 处 理 本 次 接收 的 包 体 


[检测 inputfilter 返 回 值 和 连接 是 否 仍然 可 读 ] 
[input_filter 返 加 NGX_ ERRORI] 


[ 套 接 字 上 没有 流 可 读 ] 


2) 调用 ngx_http_upstream_finalize_request 
方法 结束 请 求 


6) 将 读 事件 
添加 到 epoll 中 


7) 将 读 事件 添加 到 
定时 器 中 


图 12-6 ”ngx_http_upstream_process_body_in_memory 方 法 的 流程 图 


12.7 ”以 下 游 网 速 优 先 来 转发 啊 应 


转发 上 游 服 务 絮 的 啊 应 到 下 游客 户 逆 ， 这 项 工作 必然 是 由 上 游 事 
件 来 驱动 的 。 因 此 ， 以 下 游 网 速 优先 实际 上 只 是 意味 着 需要 开辟 一 块 
固定 长 度 的 内 存 作为 缓冲 区 。 在 图 12-5 的 第 9 步 中 会 调用 
ngx_http_upstream_send_response 方 法 加 客户 端 转发 啊 应 ， 在 该 方法 中 
将 会 判断 buffering 标 志 位 ， 如 果 buffering 为 1， 则 表明 需要 打开 缓冲 
区 ， 这 时 将 会 优先 考虑 上 游 网 速 ， 尽 可 能 多 地 接收 上 游 服 务 絮 的 啊 应 
到 内 存 或 者 磁盘 文件 中 ;而 如 果 buffering 为 0， 则 只 开辟 固定 大 小 的 组 
冲 区 内 存 ， 在 接收 上 游 服 务 右 的 响应 时 如 果 缓 冲 区 已 满 则 暂停 接收 ， 
等 待 缓 促 区 中 的 响应 发 送 给 客户 端 后 缓冲 区 会 自然 清空 ， 于 是 就 可 以 
继续 接收 上 游 服 务 絮 的 啊 应 了 。 这 种 设计 的 好 处 是 没有 使 用 大 量 内 
存 ， 这 对 提高 并 发 连接 是 有 好 处 的 ， 同 时 也 没有 使 用 磁 强 文件 ， 这 对 
降低 服务 器 负载 、 某 些 情况 下 提高 请 求 处 理 能 力也 是 有 益 的 。 


本 下 我 们 讨论 的 正 是 buffering 标 志 位 为 0 时 的 转发 啊 应 方式 ， 事 实 
上 上 ， 这 时 使 用 的 缓冲 区 也 是 接收 上 游 服务 名 头 部 时 所 用 的 内 存 ， 其 大 
小 由 ngx_http_upstream_conf_t 配 置 结构 体 中 的 buffer_size 配 置 指 定 。 


@@ 半音 buffering 标 志 位 的 值 其 实 可 以 根据 上 游 服务 器 的 响应 头 
部 而 改变 。 在 12.1.3 广 中 我 们 介绍 过 change_buffering 标 志 位 ， 当 它 的 值 


为 1 时 ， 如 果 process_header 方 法 解析 出 X-Accel-Buffering 头 部 并 设置 到 
headers_in 结 构 体 中 后 ， 将 根据 该 头 部 的 值 改变 buffering 标 志 位 。 当 X- 
Accel-Buffering 头 部 值 为 yes 时 ， 对 于 本 次 请 求 而 言 ，buffering 相 当 于 重 
设 为 1， 如 果 头 部 值 为 no， 则 相当 于 buffering 改 为 0， 除 此 以 外 的 头 部 值 
将 不 产生 作用 (参见 ngx_http_upstream_process_buffering 方 法 ) 。 
此 ， 转 发 响应 时 究竟 是 否 需要 打开 缓存 ， 可 以 在 运行 时 根据 请 求 的 不 
同 而 灵活 变换 。 


12.7.1 ”转发 响应 的 包头 


转发 响应 包头 这 一 动作 是 在 ngx_http_upstream_send_response 方 法 
中 完成 的 ， 无 论 buffering 标 志 位 是 否 为 0， 都 会 使 用 该 方法 来 发 送 响应 
的 包头 ， 图 12-7 和 图 12-9 共 同 构成 了 ngx_http_upstream_send_response 方 
法 的 完整 流程 。 先 来 看 一 下 图 12-7， 它 描述 了 单一 缓 神 区 下 是 如 何 转发 
包头 到 客户 问 ， 以 及 为 转发 包 体 做 准备 的 。 


因为 转发 啊 应 包头 这 一 过 程 并 不 存在 反复 调用 的 问题 ， 所 以 图 12-7 
中 主要 完成 了 两 项 工作 : 将 12.5T 中 解析 出 的 包头 发 送 给 下 游 的 客户 
端 、 设 置 转发 包 体 的 处 理 方法 。 下 面 详细 解释 独 12-7 搞 述 的 11 个 步 又 。 


1) 调用 ngx_http_send_header 方 法 回 下 游 的 客户 端 发 送 HTTP 包 
头 。 在 接收 上 游 服 务 句 的 啊 应 包头 时 ， 在 图 12-5 的 第 6 步 中 ，HTTP 模 块 
会 通过 process_header 方 法 解析 包头 ， 并 将 解析 出 的 值 设 置 到 


ngx_http_upstream_t 结 构 体 的 headers_in 成 员 中 ， 而 在 第 8 步 中 ， 
ngx_http_upstream_process_headers 方 法 则 会 把 headers_in 中 的 头 部 设置 
到 将 要 发 送 给 客户 端的 headers_out 结 构 体 中 ，ngx_http_send_header 方 法 
束 是 用 来 把 这 些 包 头发 送 给 客户 端的 。 这 一 步 同 时 会 将 header_sent 标 志 
位 置 为 1 (header_sent 标 志 位 在 12.4 广 中 发 送 请 求 到 上 游 服 务 器 时 会 使 
J 


人 调用 ngx_http_send_header 


方法 向 客户 端 发 送 HTTP 包 头 
[检查 来 自 客户 端的 HTTP 请求 包 体 ] 


[客户 端 请 求 的 包 体 保 存在 了 临时 文件 中 ] 


湖 pe ee 生 - [客户 端的 请 求 没有 包 体 
i ne 
一 | 


[HTTP 模 块 是 否 实 现 input_filter 方 法 ] 


[已 经 实现 了 input_filter 方 法 ] 


[HTTP 模块 没有 实现 input_filter 方 法 ] 


3 ) 用 upstream 
提供 的 默认 方法 设置 input_filter 


4) 设 置 读 事件 处 理 方法 


read_event handler 


5 ) 设 置 写 事件 处 理 方法 


write_event_handler 


6) 调 用 input_filter_init 方法 
[检查 缓冲 区 中 是 否 已 经 接收 到 包 体 ] 
[缓冲 区 中 已 经 含有 包 体 ] 


[缓冲 区 中 没有 接收 到 包 体 ] 


7 ) 调 用 input _filter 
方法 处 理 本 次 接收 到 的 响应 包 体 


9 ) 清空 buffer 
接收 缓冲 区 


8) 调 用 ngx_http_upstream_process_non_ 
buffered_downstream 方 法 


10) 调 用 ngx_http_send _special 
方法 


[检测 与 上 游 服 务 器 的 套 接 字 ] 


[ 套 接 字 上 没有 可 读 内 容 ] 
[ 套 接 字 上 有 可 读 内 容 ] 


11) 调用 ngx_http_upstream_process_non_ 
buffered_upstream 方 法 


图 12-7 ”buffering 标 志 位 为 0 时 发 送 啊 应 包头 的 流程 


2) 如 果 客 户 端的 请 求 中 有 HTTP 包 体 ， 而 且 曾 经 调用 过 11.8.1 节 中 
的 ngx_http_read_client_request_body 方 法 接收 HTTP 包 体 并 把 包 体 存 放 在 
了 临时 文件 中 ， 这 时 就 会 调用 ngx_pool_run_cleanup_file 方 法 清理 临时 
文件 。 为 什么 要 在 这 一 步 清理 临时 文件 呢 ? 因为 上 游 服 务 絮 发送 啊 应 
时 可 能 会 使 用 到 临时 文件 ， 之 后 收 到 啊 应 解析 啊 应 包头 时 也 不 可 以 清 
理 临 时 文件 ， 而 一 旦 开始 向 下 游客 户 端 转发 HTTP 啊 应 时 ， 则 意味 着 肯 
定 不 会 再 需要 客户 端 请 求 的 包 体 了 ， 这 时 可 以 关闭 、 转 移 或 者 删除 临 
时 文件 ， 具 体 动 作 由 HTTP 模块 实现 的 hander 回 调 方法 决定 。 


3) 如 果 HTTP 模 块 没有 实现 过 滤 包 体 的 input_filter 方 法 ， 则 再 把 
12.6.2 节 介绍 过 的 默认 的 ngx_http_upstream_non_buffered_filter 方 法 作为 
人 处理 包 体 的 方法 ， 它 的 工作 就 在 于 使 用 out_bufs 链 表 指 向 接收 到 的 
buffer 绥 冲 区 内 容 。 在 12.7.2 市 中 将 会 综合 介绍 它 的 作用 。 


4) 设置 读 取 上 游 服务 器 响应 的 方法 为 
ngx_http_upstream_process_non_buffered_upstream， 即 设置 upstream 中 
的 read_event_handler 回 调 方法 ， 这 样 ， 当 上 六 服 务 右 接收 到 啊 应 时 ， 通 
过 ngx_http_upstream_handler 方 法 可 最 终 调用 


ngx_http_upstream_process_non_buffered_upstream 来 接收 响应 。 


5) 将 ngx_http_upstream_process_non_buffered_downstream 设 置 为 
和 同 下 游客 户 病 发送 包 体 的 方法 ， 也 就 是 把 请 求 ngx_http_request_t 中 的 
write_event_handler 议 置 为 这 个 方法 ， 这 样 ， 一 旦 TCP 连 接 上 可 以 同 下 


游客 户 端 发 送 数据 时 ， 会 通过 ngx_http_handler 方 法 最 终 调 用 到 


ngx_http_upstream_process_non_buffered_downstream 来 发 送 啊 应 包 体 。 


6) 调用 HTTP 模 块 实现 的 input_filter_init 方 法 ( 当 HTTP 模 块 没 有 实 
现 input_filter 方 法 时 ， 它 是 默认 任何 事情 也 不 做 的 
ngx_http_upstream_non_buffered_filter_init 方 法 ) ， 为 input_filter 方 法 处 
理 包 体 做 初始 化 准备 。 


信 测 buffer 缓 冲 区 在 解析 完 包 头 后 ， 是 否 还 有 已 经 接收 到 的 包 体 
(实际 上 就 是 检查 buffer 缓 冲 区 中 的 last 指 针 是 否 等 于 pos 指 针 ) 。 如 果 
已 经 接收 到 包 体 ， 则 跳 到 第 7 步 执行 ， 如 果 没 有 接收 到 包 体 ， 则 跳 到 第 
9 步 执 行 。 


7) 调用 input_filter 方 法 处 理 包 体 。 


8) 调用 ngx_http_upstream_process_non_buffered_downstream 方 法 


把 本 次 接收 到 的 包 体 癌 下 游客 户 端 发 送 。 


9) 将 buffer 绥 冲 区 清空 ， 其 实 就 是 执行 下 面 两 行 语句 : 


u->buffer.pos = u->buffer.start,; 
u->buffer.last = u->buffer.start,; 


pos 指 针 一 般 指向 未 经 处 理 的 响应 ， 而 last 指 针 一 般 指向 刚 接 收 到 的 
响应 ， 这 时 把 它们 全 部 设 为 指向 缓冲 区 起 始 地 址 的 start 指 针 ， 即 表示 清 


空 缓冲 区 。 
10) 调用 ngx_http_send_special 方 法 ， 如 下 所 示 。 


If (ngx_http_send_special(r, NGX_HTTP_FLUSH) == NGX_ERROR) { 
ngx_http_upstream finalize_request(r, u, 0); 
return; 


} 


NGX_HTTP_FLUSH 标 志 位 意味 着 如 果 请 求 r 的 out 绥 冲 区 中 依然 有 
等 竺 发送 的 响应 ， 则 “催促 "着 发 送出 它们 。 


11) 如 果 与 上 游 服 务 器 的 连接 上 有 可 读 事件 ， 则 调用 
ngX_http_upstream_process_non_buffered_upstream 方 法 处 理 啊 应 ; 否 


则 ， 当 前 流程 结束 ， 将 控制 权 交 还 给 Nginx 框 染 。 


以 上 步 又 提 到 的 下 游 处 理 方法 
ngx_http_upstream_process_non_buffered_downstream 和 和 上游 处 理 方 法 


ngx_http_upstream_process_non_buffered_upstream 都 将 在 下 文中 介绍 。 


12.7.2 ”转发 啊 应 的 包 体 


当 接 收 到 上 游 服 务 絮 的 啊 应 时 ， 将 会 
ngx_http_upstream_process_non_buffered_upstream 方 法 处 理 连 授 上 的 这 
个 读 事 件 ， 该 方法 比较 人 简单， 下 面 直接 列举 源 代码 说 明 其 流程 。 


static void ngx_http_upstream_process_non_buffered_upstream(ngx_http_redquest 七 *r， 
ngx_http_upstream_t *u) 


ngx_connection t *c,; 


// 获取 
Nginx 与 上 游 服务 器 间 的 


TCP 连 接 


c 
c = U->peer.connection; 


// 如 果 读 取 响 应 超时 (超时 时 间 为 


read_timeout) ， 则 需要 结束 请 求 


if (c->read->timedout) { 
// ngx_http_upstream _finalize_request 方 法 可 参见 


12.9.3 节 


ngx_http_upstream finalize_request(r, u, 0); 
return; 


} 
/* 这 个 方法 才 是 真正 决定 以 固定 内 存 块 作为 缓存 时 如 何 转 发 响应 的 ， 注 


， 传 递 的 第 


剖 


ngx_http_upstream process_non_buffered request(r, 0); 


可 以 看 到 ， 实 际 接收 上 游 服务 絮 啊 应 的 其 实 是 
ngx_http_upstream_process_non_buffered_request 方 法 ， 先 不 着 急 看 它 的 
实现 ， 先 来 看 看 向 下 游客 户 病 发 送 啊 应 时 调用 的 
ngx_http_upstream_process_non_buffered_downstream 方 法 是 怎样 实现 


的 ， 如 下 所 示 。 


static void ngx_http_upstream_process_non_buffered_downstream(ngx_http_redquest 七 
*r) 
{ 

ngx_event_t *wev,; 

ngx_connection_t *c; 

ngx_http_upstream t *u; 

// 注意 ， 这 个 


Nginx 与 客户 端 之 间 的 


TCP 连 接 


Cc = r->connection,; 
U = r->upstream,; 
wev = c->write; 


/* 如 果 发 送 超 时 ， 那 么 同样 要 结束 请 求 ， 超 时 时 间 就 是 


nginx.conf 文 件 中 的 


send_timeout 配 置 项 


yh 
if (wev->timedout) { 
c->timedout = 1; 


// 注意 ， 结 束 请 求 时 传递 的 参数 是 


NGX_HTTP_REQUEST_TIME_OUT 
ngx_http_upstream finalize_request(r, u, NGX_HTTP_REQUEST_TIME_ OUT); 
return; 


} 
// 同样 调用 该 方法 向 客户 端 发 送 响应 包 体 ， 注 意 ， 传 递 的 第 


ngx_http_upstream process_non_buffered_ request(r, 1); 


无 论 是 接收 上 游 服 务 器 的 响应 ， 还 是 向 下 游客 户 端 发 送 啊 应 ， 最 
终 调用 的 方法 都 是 ngx_http_upstream_process_non_buffered_request， 唯 
一 的 区 别 是 该 方法 的 第 2 个 参数 不 同 ， 当 需要 读 取 上 游 的 响应 时 传递 的 
是 0， 当 需要 向 下 游 发 送 响 应 时 传递 的 是 1 下面 和 完 看 看 该 方法 到 底 做 
了 哪些 事情 ， 如 图 12-8 所 示 。 


图 12-8 中 的 do_write 变 量 就 是 
ngx_http_upstream_process_non_buffered_request 方 法 中 的 第 2 个 参数 ， 
当然 ， 首 先 它 还 会 有 一 个 初始 化 ， 如 下 所 示 。 


do_write = do_write || u->length == 0， 


这 里 的 length 变 量 表示 还 需要 接收 的 上 游 包 体 的 长 度 ， 当 length 为 0 
时 ， 说 明 不 再 需要 接收 上 游 的 响应 ， 那 只 能 继续 向 下 游 发 送 响 应 ， 
此 ，do_write 只 能 为 1。do_write 标 志 位 表示 本 次 是 否 同 下 游 发 送 啊 应 。 
下 面 详细 解释 图 12-8 中 的 每 个 步 又 。 


1) 如 果 do_write 标 志 位 为 1L， 则 跳 到 第 2 步 开 始 向 下 游 发 送 响 应 ; 
如 果 do_write 为 0， 则 表示 需要 由 上 游 读 取 啊 应 ， 这 时 跳 到 第 6 步 执行 。 
注意 ， 在 图 12-8 中 ， 这 一 步 吓 在 一 个 大 循环 中 执行 的 ， 也 就 是 说 ， 与 
上 、 下 游 间 的 通信 可 能 反复 执行 。 


2) 首先 检查 缓存 中 来 自 上 游 的 响应 包 体 ， 是 否 还 有 未 转发 给 下 游 
的 。 这 个 检查 过 程 很 简单 ， 因 为 每 当 在 缓冲 区 中 接收 到 上 游 的 响应 
时 ， 都 会 调用 input_filter 方 法 来 处 理 。 当 HTTP 模 块 没有 实现 该 方法 
时 ， 我 们 就 会 使 用 12.6.2 节 介绍 过 的 
ngx_http_upstream_non_buffered_filter 方 法 来 处 理 响应 ， 该 方法 会 在 
out_bufs 链 表 中 增加 ngx_buf t 绥 冲 区 (没有 分 配 实际 的 内 存 ) 指 疝 
buffer 中 接收 到 的 响应 。 因 此 ， 在 向 下 游 发 送 包 体 时 ， 直 接 发 送 
out_bufs 缓 冲 区 指向 的 内 容 即 可 ， 每 当 发 送 成 功 时 则 会 在 下 面 的 第 4 步 
中 更 新 out_bufs 缓 冲 区 ， 从 而 将 已 经 发 送出 去 的 ngx_buf t 成 员 回 收 到 
free_bufs 链 表 中 。 


事实 上 ， 检 查 是 否 有 内 容 需 要 转发 给 下 游 的 代码 是 这 样 的 : 


if (uU->out_bufs || u->busy_bufs) { .…. 


} 


可 能 有 人 会 奇怪 ， 为 什么 除了 out_bufs 缓 冲 区 链表 以 外 还 要 检查 
busy_bufs 昵 ? 这 是 因为 在 第 3 步 向 下 游 发 送 out_bufs 指 向 的 响应 时 ， 未 
必 可 以 一 次 发 送 完 。 这 时 ， 在 第 4 步 中 ， 会 使 用 busy_bufs 指 向 out_bufs 
中 的 内 容 ， 同 时 将 out_bufs 置 为 空 ， 使 得 它 在 继续 处 理 接收 到 的 响应 包 
体 的 ngx_http_upstream_non_buffered_filter 方 法 中 指向 新 收 到 的 响应 。 
因此 ， 只 有 out_bufs 和 busy_bufs 链 表 都 为 空 时 ， 才 表示 没有 响应 需要 转 
发 到 下 游 ， 这 时 跳 到 第 5 步 执 行 ， 否 则 跳 到 第 2 步 向 下 游 发 送 响 应 。 


3) 调用 ngx_http_output_filter 方 法 同 下 游 发 送 out_bufs 指 癌 的 内 
容 ， 其 代码 如 下 。 


rc = ngx_http_output_filter(r, u->out_bufs); 


2 ) 检 测 发 送 缓冲 区 
中 是 否 有 内 容 


1 ) 结合 length 成 员 和 do_write 


参数 重 置 do_write 


全 ] 
合 1 
全 


[检测 dowrite 标 志 位 ] | qo write 标 志 位 为 1] 


方法 发 送 包 体 


4) 调 用 ngx_chain_update_chains 
方法 更 新 缓冲 区 链表 


旨 向 NULL] 


[do_write 怀 志 位 为 0] 


5S) 蝎 新 buffer 
缓冲 区 中 的 pos, last 


6) 检 测 buffer 
缓冲 区 的 空闲 空间 长 度 
[检查 空闲 空间 长 度 是 否 为 0, 以 及 读 事 件 的 ready 标 志 位 ] 


[buffer 还 有 空闲 空间 ， 


7) 调 用 recv 
方法 接收 响应 


[检测 recv 返 回 值 ] 


且 ready 标志 位 为 1] 


[buffer 组 冲 区 用 尽 , 或 ready 为 0] 


[ 读 取 到 响应 包 体 ] [未 读 取 到 响应 包 体 | 
方法 处 理 包 休 


9) 设 置 do te 
标志 位 


[返回 NGX_AGAIN] 


epoll 


10) Ed 
11) 将 下 游 写 事件 添加 到 
定时 融 中 


i 


13) 将 上 游 读 事 件 添加 到 
定时 器 中 


图 12-8 ngx_http_upstream_process_non_buffered_request 方 法 的 流程 图 


读者 在 这 里 可 能 会 有 疑问 ， 在 busy_bufs 不 为 空 时 ， 不 是 也 有 内 容 
要 发 送 吗 ? 注意 ，busy_bufs 指 向 的 是 上 一 次 ngx_http_output_filter 未 发 
送 完 的 缓存 ， 这 时 请 求 ngx_http_request_t 结 构 体 中 的 out 绥 冲 区 已 经 保 
存 了 它 的 内 容 ， 不 需要 再 次 发 送 busy_bufs 了 。 


4) 调用 ngx_chain_update_chains 方 法 更 新 上 文 说 过 的 free_bufs、 
busy_bufs、out_bufs 这 3 个 缓冲 区 链表 ， 它 们 实际 上 做 了 以 下 3 件 事 情 。 


.清空 out_bufs 链 表 。 


.把 out_bufs 中 已 经 发 送 完 的 ngx_buf_t 结 构 体 清空 重 置 ( 即 把 pos 和 
last 成 员 指 向 start) ， 同 时 把 它们 追加 到 free_bufs 链 表 中 。 


:如果 out_bufs 中 还 有 未 发 送 完 的 ngx_buf t 结 构 体 ， 那 么 添加 到 
busy_bufs 链 表 中 。 这 一 步 与 ngx_http_upstream_non_buffered_filter 方 法 
的 执行 是 对 应 的 。 


5) 当 busy_bufs 链 表 为 空 时 ， 表 示 到 目前 为 止 需要 向 下 游 转发 的 响 
应 包 体 都 已 经 全 部 发 送 完 了 (也 束 是 说 ，ngx_http_request_t 结 构 体 中 的 
out 缓 冲 区 都 发 送 完 了 ) ， 这 时 将 把 buffer 接 收 缓冲 区 清空 (pos 和 last 成 
员 指 向 start) ， 这 样 ，buffer 接 收 缓冲 区 中 的 内 容 释放 后 ， 才 能 继续 接 
收 更 多 的 响应 包 体 。 


6) 获取 buffer 缓 冲 区 中 还 有 多 少 剩余 空间 ， 即 : 


size = U->buffer ,end - U->buffer .Last， 


这 里 获取 的 size 就 是 第 7 步 recv 方 法 能 够 接收 的 最 大 字 市 数 。 


当 size 大 于 0， 且 与 上 游 的 连接 上 确实 有 可 读 事件 时 (检查 读 事 件 
的 ready 标 志 位 ) ， 就 会 跳 到 第 7 步 开始 接收 响应 ， 否 则 直接 跳 到 10 步 准 
备 结束 本 次 调度 中 的 转发 动作 。 


7) 调用 recv 方 法 将 上 游 的 响应 接收 到 buffer 缓 冲 区 中 。 检 查 recv 的 
返回 值 ， 如 果 返 回 正 数 ， 则 表示 确实 接收 到 响应 ， 路 到 第 8 步 处 理 接收 
到 的 包 体 ， 如 果 返 回 NGX_AGAIN， 则 表示 期 待 epoll 下 次 有 读 事 件 时 
再 继续 调度 ， 这 时 跳 到 第 10 步 执行 ， 如 果 返 回 0， 则 表示 上 游 服务 器 关 
闭 了 连接 ， 跳 到 第 9 步 执行 。 


8) 调用 input_filter 方 法 处 理 包 体 《参考 12.6.2 贡 的 默认 处 理 方 


法 ) OG 


9) 执行 到 这 一 步 表 示 读 取 到 了 来 自 上 游 的 响应 ， 这 时 设置 
do_write 标 志 位 为 1， 同 时 跳 到 第 1 步 准 备 向 下 游 转发 刚 收 到 的 响应 。 


10) 调用 ngx_handle_write_event 方 法 将 Nginx 与 下 游 之 间 连 接 上 的 
写 事 件 添加 到 epoll 中 。 


11) 调用 ngx_add_timer 方 法 将 Nginx 与 下 游 之 间 连 接 上 的 写 事件 添 
加 到 定时 器 中 ， 超 时 时 间 束 是 配置 文件 中 的 send_timeout 配 置 项 。 


12) 调用 ngx_handle_read_event 方 法 将 Nginx 与 上 游 服 务 器 之 间 的 
连 授 上 的 读 事 件 添 加 到 epoll 中 。 


13) 调用 ngx_add_timer 方 法 将 Nginx 与 上 游 服 务 器 之 间 连 接 上 的 读 
事件 添加 a 到 定时 器 中 ， 超 时 时 间 就 是 ngx_http_upstream_conf t 配 置 结构 
体 中 的 read_timeout 成 员 。 


阅读 完 第 11 章 ， 读 者 应 该 很 熟悉 Nginx 读 / 写 事 件 的 处 理 过 程 了 。 另 
外 ， 理 解 转发 包 体 这 一 过 程 最 关键 的 是 弄 清 楚 缓 神 区 的 用 法 ， 特 别 是 
分 配 了 实际 内 存 的 buffer 绥 冲 区 与 仅仅 负 员 指 疝 buffer 绥 冲 区 内 容 的 3 个 
链表 (out_bufs、busy_bufs、free_bufs) 之 间 的 关系 ， 这 样 就 对 这 种 转 
发 过 程 的 优 缺 点 非常 清楚 了 “。 如 果 下 游 网 速 慢 ， 那 么 有 限 的 buffer 缓 冲 
区 就 会 降低 上 游 的 发 送 响应 速度 ， 可 能 对 上 游 服 务 器 带 来 高 并 发 压 
力 o 


12.8 以 上 游 网 速 优先 来 转发 啊 应 


如 果 上 游 服务 器 向 Nginx 发 送 响 应 的 速度 远 快 于 下 游客 户 端 接收 
Nginx 转 发 响应 时 的 速度 ， 这 时 可 以 通过 将 ngx_http_upstream_conf t 配 
置 结构 体 中 的 buffering 标 志 位 设 为 1， 人 允许 upstream 机 制 打开 更 大 的 缓冲 
区 来 缓存 那些 来 不 及 向 下 游 转 发 的 响应 ， 人 允许 当 达 到 内 存 构成 的 缓冲 
区 上 限时 以 磁 副 文件 的 形式 来 缓存 来 不 及 向 下 游 转发 的 响应 。 什 么 是 
更 大 的 缓冲 区 呢 ? 由 12.7 节 我 们 知道 ， 当 buffering 标 志 位 为 0 时 ， 将 使 
用 ngx_http_upstream_conf_t 配 置 结构 体 中 的 buffer_size 指 定 的 一 块 固定 
大 小 的 缓冲 区 来 转发 响应 ， 而 当 buffering 为 1 时 ， 则 使 用 bufs 成 员 指定 
的 内 存 缓冲 区 (最 多 拥有 bufs.num 个 ， 每 个 缓冲 区 大 小 固定 为 bufs.size 
字 节 ) 来 转发 响应 ， 当 上 游 响应 占 满 所 有 缓冲 区 时 ， 使 用 最 大 不 超过 
max_temp_file_size 字 节 的 临时 文件 来 缓存 响应 。 


事实 上 ， 官 方 发 布 的 ngx_http_proxy_module 反 向 代理 模块 默认 配 
置 下 束 古 使 用 这 种 方式 来 转发 上 游 服 务 器 啊 应 的 ， 由 于 它 涉及 了 多 个 
内 存 缓冲 区 的 配合 问题 ， 以 及 临时 磁 姐 文件 的 使 用 ， 导 致 它 的 实现 方 
式 异常 复杂 ，12.8.1 节 介绍 的 ngx_event_pipe_t 结 构 体 是 该 转发 方式 的 核 
心 结构 体 ， 需 要 基于 它 来 理解 转发 流程 。 


这 种 转发 响应 方式 集成 了 Nginx 的 文件 缓存 功能 ， 本 节 将 只 讨论 纯 
粹 转发 响应 的 流程 ， 不 会 涉及 文件 缓存 部 分 (以 临时 文件 缓存 啊 应 并 


不 属于 文件 缓存 ， 因 为 临时 文件 在 请 求 结 束 后 会 被 删除 ) 。 
12.8.1 ngx_event_pipe_t 结 构 体 的 意义 


如 果 将 ngx_http_upstream_conf t 配 置 结构 体 的 buffering 标 志 位 设置 
为 1， 那 么 ngx_event_pipe_t 结 构 体 必须 要 由 HTTP 模 块 创建 。 


人 @@ 注意 “upstream 中 的 pipe 成 员 默 认 指向 NULL 空 指针 ， 而 且 
upstream 机 制 永远 不 会 为 它 目 动 实 例 化 ， 因 此 ， 必 须 由 使 用 upstream 有 的 
HTTP 模 块 为 pipe 分 配 内 存 。 


ngx_event_pipe_t 结 构 体 维 护 着 上 下 游 间 转发 的 响应 包 体 ， 它 相当 
复杂 。 例 如 ， 缓 冲 区 链表 ngx_chain_t 类 型 的 成 员 就 定义 了 6 个 (包括 
free_raw_bufs、in、out、free、busy、preread_bufs) ， 为 什么 要 用 如 此 
复杂 的 数据 结构 支撑 看 似 简单 的 转发 过 程 呢 ?这 是 因为 Nginx 的 宗旨 就 
是 高 效率 ， 所 以 它 绝 不 会 把 相同 内 容 复 制 到 两 块 内 存 中 ， 而 同一 块 内 
存 如 果 既 要 用 于 接收 上 游 发 来 的 响应 ， 又 要 准备 向 下 游 发 送 ， 很 可 能 
还 要 准备 写 入 临时 文件 中 ， 这 就 带 来 了 很 高 的 复杂 度 ， 
ngx_event_pipe_t 结 构 体 的 任务 就 在 于 解决 这 个 问题 。 


理解 这 个 结构 体 中 各 个 成 员 的 含义 将 会 帮助 我 们 弄 清 楚 buffering 为 
1 时 转发 啊 应 的 流程 ， 特 别 是 可 以 弄 清 楚 Nginx 绝 不 复制 重复 内 存 的 高 
效 做 法 是 如 何 实现 的 。 当 然 ， 我 们 也 可 以 先 跳 到 12.8.2 市 综合 理解 这 种 


转发 方式 下 的 运行 机 制 ， 再 针对 流程 中 过 到 的 ngx_event_pipe_t 结 构 体 
中 的 成 员 返 回 到 本 和 来 查询 其 意义 。 下 面 看 一 下 它 各 个 成 员 的 意义 。 


typedef struct ngx_event_pipe_s ngx_event pipe_t; 
// 处 理 接 收 自 上 游 的 包 体 的 回调 方法 原型 


typedef ngx_int_t (*ngx_event_ pipe_ input_filter pt) (ngx_event pipe t *p, 
ngx_buf_t *buf); 
// 向 下 游 发 送 响 应 的 


五 


调 方法 原型 


typedef ngx_int _t (*ngx_event pipe output_filter_pt)(void *data，ngx_chain _t 
*chain); 
struct ngx_event pipe s { 


// Nginx 与 上 游 服务 器 间 的 连接 


ngx_connection_t *upstream; 
// Nginx 与 下 游客 户 端 间 的 连接 


ngx_connection t *downstream; 
/* 直 接 接收 自 上 游 服 务 器 的 缓冲 区 链表 ， 注 意 ， 这 个 链 对 


中 的 顺序 是 逆序 的 ， 也 就 是 说 ， 链 表 前 端的 


Al 


ey 
Tl 
ek 
a 
TEP 
人 


ngx_buf_t 缓 冲 区 指向 的 是 后 接收 到 的 


ngx_buf_t 缓 冲 区 指向 的 是 先 接收 到 的 响应 。 因 此 ， 


free_raw_bufs 链 表 仅 在 接收 响应 时 使 用 
A 
ngx_chain_t *free_raw_bufs; 


/* 表 示 接 收 到 的 上 游 响 应 缓冲 区 。 通 常 ， 


in 链 表 是 在 


input_filter 方 法 中 设置 的 ， 可 参考 


ngx_event_pipe_copy_input_filter 方 法 ， 它 会 将 接收 到 的 缓冲 区 设置 到 


in 链表 中 


*/ 
ngx_chain_t *in; 


// 指向 刚刚 接收 到 的 一 个 缓冲 区 


ngx_chain_t **]last_in; 


/* 保 存 着 将 要 发 送 给 客户 端的 缓冲 区 链 于 
表 中 写 入 文件 的 缓冲 区 添加 到 


。 在 写 入 临时 文件 成 功 时 ， 会 把 


从 由 


out 链 表 中 


ngx_chain t *out 


// 指向 刚 加 入 


out 链 表 的 缓冲 区 ， 暂 无 实际 意义 


ngx_chain t **]last_ out; 
// 等 待 释放 的 缓冲 区 


ngx_chain_t *free,; 
/* 设 置 


busy 绥 冲 区 中 待 发 送 的 响应 长 度 触 发 值 ， 当 达到 
busy_size 长 度 时 ， 必 须 等 待 


busy 缓 冲 区 发 送 了 足够 的 内 容 ， 才 能 继续 发 送 


out 和 


in 缓冲 区 中 的 内 容 


*/ 
ssize_t busy_size,; 
/* 表 示 上 次 调 


洪 


中 的 缓冲 区 已 经 保存 到 请 求 的 


ngx_http_output_filter 方 法 发 送 响 应 时 没有 发 送 完 的 缓冲 区 链表 。 这 
out 链 表 中 ， 
busy 仅 用 于 记录 还 有 多 大 的 响应 正 等 待 发 送 


*/ 
ngx_chain_t *busy; 


/处 理 接收 到 的 来 自 上 游 服务 器 的 缓冲 区 。 一 般 使 用 
upstream 机 制 默认 提供 的 


ngx_event_pipe_copy_input_filter 方 法 作为 


input_filter*/ 
ngx_event_pipe_ input_filter_pt input_filter; 
/用 于 


input_filter 方 法 的 成 员 ， 一 般 将 它 设 置 为 


ngx_http_request_t 结 构 体 的 地 址 


SS 
void *input_ctx; 


/* 表 示 向 下 游 发 送 响 应 的 方法 ， 默 认 使 


ngx_http_output_filter 方 法 作为 


output_filter*/ 
ngx_event_pipe _ output_filter_pt output_ filter; 
// 指向 


ngx_http_request_t 结 构 体 


void *output_ctx; 


// 标志 位 ， 


1 时 表示 当前 已 经 读 取 到 上 游 的 响应 


unsigned read :1 
/* 标 志 位 ， 为 


1 时 表示 启用 文件 缓存 。 本 章 描述 的 场景 都 忽略 了 文件 缓存 ， 也 就 是 默认 


cacheable 值 为 

0O*/ 
unsigned cacheable:1,; 
// 标志 位 ， 为 


1 时 表示 接收 上 游 响 应 时 一 次 只 能 接收 一 个 


ngx_buf_t 缓 冲 区 


unsigned Single_buf:1' 
/* 标 志 位 ， 为 


1 时 一 旦 不 再 接收 上 游 响应 包 体 ， 
如 没有 用 于 写 入 临时 文件 或 者 用 了 


向 下 游客 户 端 释放 ， 就 把 缓冲 区 指向 的 内 存 释 放 给 


poo1 内 存 池 

*/ 
unsigned free_bufs:1， 
/* 提 供给 

HTTP 模 块 在 


input_filter 方 法 中 使 用 的 标志 位 ， 表 示 


Nginx 与 上 游 间 的 交互 已 结束 。 如 果 
HTTP 模 块 在 解析 包 体 时 ， 认 为 从 业务 上 需要 结束 与 上 游 间 的 连接 ， 那 么 可 以 把 


upstream_done 标 志 位 置 为 


1*/ 
unsigned upstream_ done:1; 
/*Nginx 与 上 游 服务 器 之 间 的 连接 出 现 错误 时 ， 


upstream_error 标 志 位 为 
1， 一 般 当 接收 上 游 响 应 超时 ， 或 者 调 


recv 接 收 出 现 错误 时 ， 就 会 把 该 标志 位 置 为 


1*/ 
unsigned upstream error:1; 


/* 表 示 与 上 游 的 连接 状态 。 当 
Nginx 与 上 游 的 连接 已 经 关闭 时 ， 


upstream_eof 标 志 位 为 


将 尽 可 能 地 立刻 释放 缓冲 区 。 所 谓 尽 可 能 是 指 ， 一 旦 


这 个 缓冲 


区 


被 引用 ， 


1*/ 
unsigned upstream eof:1; 


/* 表 示 和 暂时 阻塞 住 读 取 上 游 响 应 的 流程 ， 期 待 通过 向 下 游 发 送 啊 应 来 清理 HH 


冲 区 接收 响应 。 也 就 是 说 ， 


upstream_blocked 标 志 位 为 


1 时 会 在 


ngx_event_pipe 方 法 的 循环 中 先 调 


ngx_event_pipe_write_to_downstream 方 法 发 送 响应 ， 然 后 再 


ngx_event_pipe_read_upstream 方 法 读 取 上 游 响应 


2 
unsigned upstream blocked:1; 
// downstream_done 标 志 位 为 


1 时 表示 与 下 游 间 的 交互 已 经 结束 ， 目 前 无 意义 


unsigned downstream done:1; 
/*Nginx 与 下 游客 户 端 间 的 连接 出 现 错误 时 ， 


downstream_error 标志 位 为 


1。 在 代码 中 ， 一 般 是 向 下 游 发 送 响应 超时 ， 或 者 使 


> 


ngx_http_output_filter 方 法 发 送 响应 却 返 回 
NGX_ERROR 时 ， 把 

downstream_error 标志 位 设 为 

1*/ 


unsigned downstream error:1; 
/* cyclic_temp_file 标 志 位 为 


1 时 会 试图 复 用 临时 文件 中 曾经 使 用 过 的 空间 。 不 建议 将 


cyclic_temp_file 设 为 


1。 它 是 


ngx_http_upstream_conf_t 配 置 结构 体 中 的 同名 成 员 赋 值 的 


SA 
unsigned cyclic temp_file:1; 
// 表示 已 经 分 配 的 缓冲 区 数目 


allocated 受 到 


bufs .num 成 员 的 限制 


ngx_int_t allocated; 
/*bufs 记 录 了 接收 上 游 响 应 的 内 存 缓冲 区 大 小 ， 其 中 


bufs ,size 表 示 每 个 内 存 缓冲 区 的 大 小 ， 而 


空闲 的 缓冲 


jE 


~ 
"/ 


t 


上 


tH 的 组 


bufs .num 表 示 最 多 可 以 有 


num 个 接收 缓冲 区 


Wy 
ngx_bufs_t bufs; 
// 用 于 设置 、 比 较 缓 冲 区 链 对 


ngx_buf_t 结 构 体 的 


Kt 
二 


tag 标 志 位 


ngx_buf_tag_t tag 
// 已 经 接收 到 的 上 游 响应 包 体 长 度 


off_t read length,; 
/* 与 


ngx_http_upstream_conf_t 配 置 结构 体 中 的 


max_temp_file_size 含 义 相 同 ， 同 时 它们 的 值 也 是 相等 的 ， 表 示 临 时 文件 的 最 大 长 度 


*/ 
off_t max_temp_file size; 
/* 与 


ngx_http_upstream_conf_t 配 置 结构 体 中 的 


temp_file_write_size 含 义 相同 ， 同 时 它们 的 值 也 是 相等 的 ， 表 示 一 次 写 入 文件 时 的 最 大 长 度 


*/ 
ssize t temp_ file write size; 


// 读 取 上 游 响 应 的 超时 时 间 


ngx_msec_t read timeout; 


// 向 下 游 发 送 响 应 的 超时 时 间 


ngx_msec_t send timeout; 


// 向 下 游 发 送 响应 时 ， 
TCP 连 接 中 设置 的 


send_lowat“ 水 位 ” 


ssize_t send_ lowat; 


// 用 于 分 配 内 存 缓冲 区 的 连接 池 对 象 


ngx_pool_t *pool， 
// 用 于 记录 日 志 的 


ngx_1og_t 对 象 


ngx_log_t *1og， 
// 表示 在 接收 上 游 服务 器 响应 头 部 阶段 ， 已 经 读 取 到 的 响应 包 体 


ngx_chain_t *preread_bufs; 


// 表示 在 接收 上 游 服务 器 响应 头 部 阶段 ， 已 经 读 取 到 的 响应 包 体 长 度 


Size_t preread size,; 


// 仅 用 于 缓存 文件 的 场景 ， 本 章 不 涉及 ， 故 不 再 详 进 该 缓冲 区 


Xx 


ngx_buf_t *buf_to_file; 
// 存放 上 游 响应 的 临时 文件 ， 最 大 长 度 


max_temp_file_size 成 员 限 制 


ngx_temp_file t *temp_file; 
// 已 使 用 的 


ngx_buf_t 缓 冲 区 数目 


int num; 


}; 


注意 ，ngx_event_pipe_t 结 构 体 仅 用 于 转发 响应 。 


12.8.2 ”转发 响应 的 包头 


开始 转发 啊 应 也 是 通过 ngx_http_upstream_send_response 方 法 执行 
的 。 图 12-9 展 示 了 转发 啊 应 包头 和 初始 化 ngx_event_pipe_t 结 构 体 的 流 
程 。 


1) 调用 ngx_http_send_header 


方法 向 客户 端 发 送 HTTP 包 头 
[检查 来 自 客户 端的 HTTP 请 求 包 体 ] 


[ 求 没有 包 体 
[客户 端 请 求 的 包 体 保 存在 了 临时 文件 中 ] 或 者 包 体 没有 保存 在 临时 文件 中 ] 


2 ) 调 用 ngx_pool_ run_ cleanup_file 


方法 清理 文件 


3) 初始 化 ngx_event_pipe tt 
结构 体 


4) 初 始 化 预 读 缓冲 
区 链表 


5) 设置 上 游 读 事件 处 理 方法 


read_event handler 


6) 设 置 下 游 写 事件 处 理 方法 


write _event handler 


7) 调 用 ngx_http_upstream_process_upstream 


方法 处 理 上 游 响应 


各 
图 12-9 ”buffering 标 志 位 为 0O 时 转发 响应 包头 的 流程 图 


下 面 说 明 一 下 图 12-9 中 的 步骤 。 


1) 首先 调用 ngx_http_send_header 方 法 向 下 游客 户 端 发 送 
ngx_http_request_t 结 构 体 的 headers_out 中 设置 过 的 HTTP 啊 应 包头 。 


2) 如 果 客 户 端 请 求 中 存在 HITP 包 体 ， 而 且 包 体 已 经 保存 到 临时 
文件 中 了 ， 这 时 将 会 调用 ngx_pool_run_cleanup_file 方 法 清理 临时 文 
件 ， 以 释放 不 必要 的 资源 。 这 里 的 第 1 步 和 第 2 步 与 图 12-8 中 的 完全 一 
样 ， 不 再 详 述 。 


3) ngx_http_upstream _t 结 构 体 中 的 pipe 成 员 并 不 是 在 这 一 步 中 创 
建 ， 它 仅 在 这 一 步 中 初始 化 部 分 成 员 ， 因 此 ， 一 旦 pipe 到 这 一 步 还 没有 
创建 ， 就 会 出 现 内 存 访问 越界 ，3 引 发 站 重 错误 。ngx_event_pipe_t 结 构 
体 的 初始 化 大 概 包 括 以 下 部 分 


// 注意 ， 这 里 是 直接 引用 必须 分 配 过 内 存 的 


pipe 指 针 


ngx_event_pipe_t* p = u->pipe; 


/* 设 置 向 下 游客 户 端 发 送 响 应 的 方法 为 


ngx_http_output_filter， 该 方法 在 第 


11 章 中 介绍 过 


4 
p->output_filter = (ngx_event_pipe _ output_filter_pt) ngx_http_output_filter; 
/*output_ctx 指 向 当前 请 求 的 


ngx_http_request_t 结 构 体 ， 这 是 因为 接 下 来 转发 包 体 的 方法 都 只 接受 


公 


ngx_event_pipe_t 参 数 ， 且 只 能 


output_ctx 成 员 获 取 到 表示 请 求 的 
ngx_http_request_t 结 构 体 
*/ 


p->output_ctx = r; 


// 设置 转发 响应 时 启用 的 每 个 缓冲 区 的 


I 


tag 标 志 位 


p->tag = u->output. tag; 
// bufs 指 定 了 内 存 缓冲 区 的 限制 


p->bufs = u->conf->bufs; 


// 设置 
busy 缓 冲 区 中 待 发 送 的 响应 长 度 触 发 值 


p->busy_ slize = u->conf->busy_buffers_size; 
// upstream 在 这 里 被 初始 化 为 


Nginx 与 上 游 服务 器 之 间 的 连接 


p->upstream = u->peer.connection; 
// downstream 在 这 里 被 初始 化 为 


Nginx 与 下 游客 户 端 之 间 的 连接 


p->downstream = c; 


// 初始 化 用 于 分 配 内 存 缓冲 区 的 内 存 池 


p->pool = r->pool; 
// 初始 化 记录 日 志 的 


log 成 员 


p->1og = c->1l0g; 
// 设置 临时 存放 上 游 响 应 的 单个 缓存 文件 的 最 大 长 度 


p->max_temp_file size = U->conf->max_temp_file_size， 
// 设置 一 次 写 入 文件 时 写 入 的 最 大 长 度 


p->temp_file_write_size = U->conf->temp_file_write_size， 
// 以 当前 


location 下 的 配置 来 设置 读 取 上 游 啊 应 的 超时 时 间 


p->read_ timeout = u->conf->read_ timeout; 
// 以 当前 


location 下 的 配置 来 设置 发 送 到 下 游 的 超时 时 间 


p->send_timeout = clcf->send_timeout; 


// 设置 向 客户 端 发 送 响应 时 


TCP 中 的 


send_lowat“ 水 位 ” 


p->send_lowat = Clcf->send_ lowat 


4) 初始 化 preread_bufs 预 读 缓冲 区 链表 〈 所 谓 预 读 ， 就 是 在 读 取 包 
头 时 也 预先 读 取 到 了 部 分 包 体 ) ， 注 意 ， 该 链表 中 的 缓冲 区 都 是 不 会 
分 配 内 存 来 存放 上 游 啊 应 内 容 的 ， 而 仅 使 用 ngx_buf t 结 构 体 指 癌 实 际 
的 存放 响应 包 体 的 内 存 。 如 何 初 始 化 preread_bufs 呢 ? 如 下 所 示 。 


p->preread_bufs->buf = &u->buffer; 
p->preread_bufs->next = NULL; 
p->preread size = u->buffer.last - u->buffer.pos; 


实际 上 束 是 把 preread_bufs 中 的 缓冲 区 指向 存放 头 部 的 buffer 绥 促 
区 ， 在 图 12-11 中 的 第 1 步 会 介绍 它 的 用 法 。 


5) 设置 处 理 上 游 读 事件 回调 方法 为 


ngx_http_upstream_process upstream ° 


6) 设置 处 理 下 游 写 事件 的 回调 方法 为 


ngx_http_upstream_process_downstream ° 


7) 调用 ngx_http_upstream_process_upstream 方 法 处 理 上 游 发 来 的 响 
订 包 体 。 


ngx_event_pipe _t 结 构 体 是 打开 缓存 转发 响应 的 关键 ， 下 面 的 章节 
中 我 们 会 一 直 与 它 < 打 交道 * 。 


12.8.3 ”转发 啊 应 的 包 体 


在 图 12-9 中 我 们 看 到 ， 处 理 上 游 读 事件 的 方法 是 
ngx_http_upstream_process_upstream， 处 理 下 游 写 事件 的 方法 是 


ngx_http_upstream_process_downstream， 但 它们 最 终 都 是 通过 
ngx_event_pipe 方 法 实现 缓存 转发 啊 应 功能 的 类似 于 在 12.7.2 节 中 介 
绍 过 的 无 缓存 转发 啊 应 情形 ， 
ngx_http_upstream_process_non_buffered_upstream 方 法 负责 处 理 上 游 读 
事件 ，ngx_http_upstream_process_non_buffered_downstream 方 法 负责 处 
理 下 游 写 事件 ， 但 它们 最 终 都 是 通过 
ngx_http_upstream_process_non_buffered_request 方 法 实现 转发 啊 应 功能 
的 ) 。 无 论 是 否 打 开 缓 存 ， 它 们 的 代码 都 非常 相似 ， 所 以 本 市 不 再 罗 
列 这 两 种 方法 的 代码 ， 直 接 开 始 介绍 ngx_event_pipe 方 法 ， 移 来 看 看 它 


ngx_int_t ngx_event_pipe(ngx_event_pipe_t *p, ngx_int_t do_write) 


其 中 ，p 参 数 正 是 负 员 转发 啊 应 的 ngx_event_pipe_t 结 构 体 ， 而 
do_write 则 是 标志 位 ， 其 为 1 时 表示 需要 向 下 游客 户 端 发 送 啊 应 ， 为 0 时 
表示 仅 需要 由 上 游客 户 端 接收 响应 。 图 12-10 给 出 了 ngx_event_pipe 方 法 
的 流程 图 ， 该 方法 通过 调用 ngx_event_pipe_read_upstream 方 法 读 取 上 游 


啊 应 ， 调 用 ngx_event_pipe_write_to_downstream 方 法 回 下 游 发 送 啊 应 ， 
因此 ， 在 流程 图 中 暂时 看 不 出 内 存 缓冲 区 与 临时 缓存 文件 的 用 法 。 


下 面 介 绍 图 12-10 中 的 10 个 步骤 。 


1) 检查 do_write 标 志 位 ， 如 果 do_write 为 0， 则 直接 跳 到 第 5 步 开 始 
读 取 上 游 服 务 器 发 来 的 啊 应 ， 如 果 do_write 为 1， 则 继续 执行 第 2 步 。 


2) 调用 ngx_event_pipe_write_to_downstream 方 法 (参见 12.8.5 节 ) 
向 下 游客 户 端 发 送 响应 包 体 ， 检 测 其 返回 值 : 如 果 返 回 NGX_OK， 则 
跳 到 第 5 步 处 理 上 游 的 读 事件 ， 如 果 返 回 NGX_ABORIT， 则 跳 到 第 3 步 
执行 ， 如 果 返 回 NGX_BUSY， 则 跳 到 第 4 步 执行 。 


1 ) 检测 do write 
标志 位 


[do_write 标志 位 为 1] [do write 标志 位 为 0] 


2) 调 用 ngxeventpipe_write to_downstream 
方法 向 下 游 发 送 响 应 
[检查 方法 返回 值 ] 


和 


[返回 NGX_OK] [返回 NGX_BUSY] 


[返回 NGX_ABORT ] 


5) 调 用 ngx_event_pipe_read_upstream 


方法 由 上 游 读 取 响 应 
[检查 方法 返回 值 ] 


[返回 NGX_ABORT] 


[返回 NGX_OK] [没有 可 读 内 容 ] 3 返回 
NGX_ABORT 
6) 设置 do write 
标志 位 为 1 


7 HP A 


8) 将 下 游 写 事件 添加 到 


9) 将 上 游 读 事件 添加 到 NGX_OK 


epoll 中 


10) 将 上 游 读 事件 添加 到 和 


定时 需 


图 12-10 ngx_event_pipe 方 法 的 流程 图 


3) ngx_event_pipe 方 法 结束 ， 返 回 NGX_ABORT 表 示 请 求 处 理 失 
败 。 


4) ngx_event_pipe 方 法 结束 ， 返 回 NGX_OK 表 示 本 次 暂 不 往 下 执 


5) 调用 ngx_event_pipe_read_upstream 方 法 (参见 12.8.4 节 ) 读 取 上 
游 服 务 妖 的 响应 ， 同 时 检测 其 返回 值 以 及 ngx_event_pipe_t 结 构 体 中 的 
read 和 upstream_blocked 标 志 位 : 如 果 返 回 NGX_ABORT， 则 跳 到 第 3 步 
执行 ， 否 则 检查 read 和 upstream_blocked 标 志 位 。 如 果 这 两 个 标志 位 同 
时 为 0， 那 么 跳 到 第 7 步 执 行 ， 如 果 这 两 个 标志 位 有 任 一 个 为 1， 则 表示 
需要 向 下 游 发 送 读 到 的 响应 ， 跳 到 第 6 步 执 行 。 在 这 里 ，read 标 志 位 为 1 
时 表示 ngx_event_pipe_read_upstream 方 法 执行 后 读 取 到 了 啊 应 ， 而 
upstream_blocked 为 1 时 则 表示 执行 后 需要 和 暂时 停止 读 取 上 游 响 应 ， 需 要 
通过 向 下 游 发 送 啊 应 来 清理 出 空间 缓冲 区 ， 以 供 
ngx_event_pipe_read_upstream 方 法 再 次 读 取 上 游 的 啊 应 。 


6) 设置 do_write 标 志 位 为 1， 继 续 跳 到 第 1 步 向 下 游 发 送 刚 收 到 的 
上 游 响 应 ， 重 复 这 个 循环 。 


7) 调用 ngx_handle _read_event 方 法 将 上 游 的 读 事件 添加 到 epoll 
中 ， 等 每 下 一 次 接收 到 上 游 啊 应 的 事件 出 现 。 


8) 调用 ngx_add_timer 方 法 将 上 游 的 读 事 件 添加 到 定时 如 中 ， 超 时 
时 间 就 是 ngx_event_pipe_t 结 构 体 的 read_timeout 成 员 (参见 图 12-9 的 第 3 
步 关 于 该 成 员 的 初始 化 ) 。 


9) 调用 ngx_handle_ write _event 方 法 将 下 游 的 写 事件 添 加 到 epoll 
中 ， 等 竺 下 一 次 可 以 向 下 游 发 送 啊 应 的 事件 出 现 。 


10) 调用 ngx_add_timer 方 法 将 下 游 的 写 事件 添加 到 定时 器 中 ， 超 
时 时 间 就 是 ngx_event_pipe_t 结 构 体 的 send_timeout 成 员 (参见 图 12-9 的 
第 3 步 关于 该 成 员 的 初始 化 ) 。 


可 以 看 到 ，ngx_event_pipe 方 法 在 没有 涉及 缓存 细 世 的 情况 下 设计 
了 转发 响应 的 流程 ， 它 是 通过 调用 ngx_event_pipe_read_upstream 方 法 和 
ngx_event_pipe_write_to_downstream 方 法 ， 以 及 检测 它们 的 返回 值 来 把 
握 缓 存 啊 应 的 转发 ， 再 把 事件 与 epoll 和 定时 胡 关 联 起 来 的 。 下 面 我 们 
将 详细 描述 如 何 读 取 啊 应 、 如 何 分 配 内 存 缓冲 区 、 如 何 通过 写 入 临时 
文件 释放 缓冲 区 、 如 何 通过 向 下 游 发 送 啊 应 来 更 新 缓冲 区 。 


12.8.4 ngx_event_pipe_read_upstream 方 法 


ngx_event_pipe_read_upstream 方 法 负责 接收 上 游 的 啊 应 ， 在 这 个 过 
程 中 会 涉及 以 下 4 种 情况 。 


-接收 啊 应 头 部 时 可 能 接收 到 部 分 包 体 。 


.如 果 没 有 达到 bufs.num 上 限 ， 那 么 可 以 分 配 bufs.size 大 小 的 内 存 块 


充当 接收 缓冲 区 。 

如 来 恰好 下 游 的 连接 处 于 可 写 状态 ， 则 应 该 优先 发 送 啊 应 来 清理 
出 空 朵 缓冲 区 。 

如果 缓冲 区 全 部 写 满 ， 则 应 该 写 入 临时 文件 。 


这 4 种 情况 会 造成 ngx_event_pipe_read_upstream 方 法 较为 复杂 ， 特 
别 是 任何 一 个 ngx_buf t 缓 冲 区 都 存在 复 用 的 情况 ， 什 么 时 候 释 放 、 重 
复 使 用 它们 会 很 太 烦 ， 因 此 ， 青 先 把 纯粹 地 接收 自 上 游 缓冲 区 的 代码 
提取 出 来 ， 概 括 为 流程 图 ， 如 图 12-11 所 示 ， 读 者 首先 看 看 到 底 怎样 接 


收 上 游 响 应 ， 然 后 再 来 分 析 ngx_event_pipe_read_upstream 方 法 。 


[检查 preread_bufs 预 读 缓冲 区 链表 指针 是 否 为 空 ] 


[preread_bufs 不 为 空 ] 


[preread_bufs 为 空 , 检查 free_raw_bufs 链 表 指 针 是 否 为 空 ] 


1 ) 准备 处 理 preread_bufs 
中 存放 包 体 的 缓冲 区 


[free_raw bufs 不 为 空 ] 


[free_rawbufs 为 空 , 检查 allocated 是 否 小 于 bufs.num] 
2 ) 使 用 free_raw_bufs 
接收 上 游 啊 应 


[已 分 配 缓冲 区 数目 allocated 小 于 bufs.num ] 


[allocated 大 于 或 等 于 bufs. num , 检查 是 否 可 向 下 游 发 送 响 应 ] 
3 ) 分配 新 的 缓冲 区 
接收 上 游 啊 应 


[Nginx 与 下 游 的 连接 上 可 写 事件 已 经 准备 好 ] 


[下 游 写 事 件 不 可 用 , 检查 临时 文件 是 否 达 到 max_temp _file _size] 
4)upstream_blocked 标 志 位 置 为 1， 
返回 NGX_OK 


[临时 缓存 文件 未 达到 上 限 ] 


5) 将 上 游 响 应 写 入 
临时 文件 


[临时 文件 大 小 已 达到 限制 ] 


6) 调 用 recv_chain 
方法 接收 上 游 响应 包 体 


7) 将 新 接收 到 的 缓冲 区 置 于 
free_rawbufs 链表 未 尾 


®@ 
图 12-11 使 用 缓冲 区 接收 上 游 啊 应 的 流程 图 


图 12-11 中 的 步 又 很 清晰 ， 主 要 是 在 寻找 使 用 哪 一 块 缓冲 区 接收 上 
游 啊 应 。 注 意 ， 在 选择 缓冲 区 时 也 有 优先 级 。 下 面 我 们 分 析 其 中 的 7 个 
步 又 。 


1) 首先 检查 ngx_event_pipe_t 结 构 体 中 的 preread_bufs 绥 冲 区 〈 若 无 
特殊 说 明 ， 以 下 介绍 的 成 员 都 属于 ngx_event_pipe_t 结 构 体 ) ， 它 存放 
着 在 接收 啊 应 包头 时 可 能 接收 到 的 包 体 (图 12-9 中 的 第 4 步 初始 化 了 
preread_bufs 缓 冲 区 ) ， 如 果 preread_bufs 中 有 内 容 ， 意 味 着 需要 优先 处 
理 这 部 分 包 体 ， 而 不 是 去 接收 更 多 的 包 体 ， 这 样 ， 接 收 流程 就 结束 
了 “。 如 果 preread_bufs 绥 冲 区 是 空 的 ， 那 么 继续 向 下 执行 。 


2) 检查 free_raw_bufs 绥 冲 区 链表 ，free_raw_bufs 用 来 表示 一 次 
ngx_event_pipe_read_upstream 方 法 调用 过 程 中 接收 到 的 上 游 啊 应 。 注 
意 ，free_raw_bufs 链 表 中 缓冲 区 的 顺序 与 接收 顺序 是 相反 的 ， 每 次 使 用 
绥 冲 区 接收 到 上 游 发 来 的 啊 应 后 ， 都 会 把 该 缓冲 区 添加 到 free_raw_bufs 
末尾 。 如 果 free_raw_bufs 为 空 ， 则 继续 第 3 步 执 行 ， 否 则 ， 跳 到 第 6 步 使 
用 free_raw_bufs 绥 冲 区 接收 上 游 啊 应 。 


3) 将 已 经 分 配 的 缓冲 区 数量 (allocated 成 员 ) 与 bufs.num 配 置 相 
比 ， 如 采 allocated 小 于 bufs.num， 则 可 以 从 pool 内 存 池 中 分 配 到 一 块 新 
的 缓冲 区 ， 再 跳 到 第 6 步 用 这 块 缓冲 区 来 接收 上 游 啊 应 ， 否 则 说 明 分 配 
的 缓冲 区 已 经 达到 上 限 ， 跳 到 第 4 步 继续 向 下 执行 。 


4) 检查 Nginx 与 下 游 的 连接 downstream 成 员 ， 检 查 它 的 写 事件 的 
ready 标 志 位 ， 如 果 ready 为 1， 则 表示 当前 可 以 向 下 游 发 送 响应 ， 再 检 
查 写 事件 的 delayed 标 志 位 ， 如 果 delayed 为 0， 则 说 明 并 不 是 由 于 限 速 才 
使 得 写 事 件 准 备 好 ， 这 两 个 条 件 都 满足 时 表明 应 当 由 向 下 游 发 送 响应 
来 释放 缓冲 区 ， 以 期 可 以 使 用 释放 出 的 空 闪 缓冲 区 再 接收 上 游 响 应 。 
怎么 做 到 呢 ? 将 upstream_blocked 置 为 1 即 可 。 当 无 法 满足 上 述 条 件 时 ， 
继续 执行 第 5 步 。 


5) 检查 临时 文件 中 已 经 写 入 的 响应 内 容 长 度 (也 就 是 temp_file- 
>offset) 是 否 达 到 配置 上 限 (也 就 是 max_temp_file_size 配 置 ) ， 如 果 
已 经 达到 ， 则 和 暂时 不 再 接收 上 游 啊 应 ;如果 没有 达到 ， 调 用 
ngx_event_pipe_write_chain_to_temp_file 方 法 将 响应 写 入 临时 文件 中 。 
下 面 简单 地 看 看 这 个 方法 做 了 些 什 么 : 首先 将 问 缓冲 区 链表 中 的 内 容 写 
入 temp_file 临 时 文件 中 ， 再 把 写 入 临时 文件 的 ngx_buf t 绥 冲 区 由 in 缓冲 
区 链表 中 移出 ， 添 加 到 out 绥 冲 区 链表 中 。 在 写 入 临时 文件 成 功 后 ， 跳 
到 第 6 步 使 用 free_raw_bufs 缓 冲 区 接收 上 游 响 应 。 


6) 调用 recv_chain 方 法 接收 上 游 的 响应 。 
7) 将 新 接收 到 的 缓冲 区 置 到 free_raw_bufs 链 表 的 最 后 。 


图 12-11 中 的 这 7 个 步骤 将 会 找 出 一 个 缓冲 区 接收 上 游 的 啊 应 ， 并 把 
这 个 绥 冲 区 添加 到 free_raw_bufs 链 表 中 ， 下 面 我们 以 此 为 基础 ， 看 看 图 


12-12 中 mgx_event_pipe_read_upstream 方 法 是 如 何 处 理 free_raw_bufs 链 表 
的 。 


图 12-12 展 示 了 ngx_event_pipe_read_upstream 方 法 的 全 部 流程 ， 其 
中 主要 包括 一 个 接收 上 游 啊 应 的 循环 ， 而 每 一 次 接收 到 上 游 啊 应 后 义 
会 有 一 个 循环 来 处 理 free_raw_bufs 链 表 中 的 全 部 缓冲 区 ， 下 面 详细 分 析 


一 下 这 11 个 步骤 。 


1 检查 上 游 连接 是 否 结束 ， 
或 者 暂 无 可 读 内 容 


肥 上 游 响 应 ] 


结束 , 或 者 暂 不 可 读 ] 


[upstream 
2) 使 用 缓冲 区 读 
取 上 游 响应 


[上 游 关 闭 连接 ] 
[有 需要 处 理 的 在 取 到 的 响应 ] 


3 ) 置 read 
标志 位 为 1 


[返回 NGX_AGAIN 1] 


4) 遍 历 待 处 理 缓冲 区 链表 中 的 
n 


xc_buf ft 


8) 置 u pstream_eof 为 1 
表示 上 游 连接 结束 


[直接 返回 NGX_OK ] 
5 ) 调 用 ngx_event_pipe_remove_ 
shadow_links 方 法 
[检查 读 取 到 的 内 容 是 否 全 部 

保存 在 当前 缓冲 区 中 ] 


9) 检查 上 游 连 接 
是 否 关 闭 


[ 读 取 到 的 内 容 小 于 当前 缓冲 区 大 小 ] 
-或 等 于 当前 缓冲 区 的 大 小 ] 


[ 读 取 到 的 内 容 大 : 
[上 游 连接 关闭 ] 


方法 处 理 包 体 


[检查 free_bufs 标志 位 ] 


6) 调 用 inputfilter 
方法 处 理 包 体 


7) 将 free_raw_bufs 
指向 剩余 缓冲 区 


[上 游 连接 未 关闭 ] 


[free_bufs 为 0] 
11) 释放 缓冲 区 


图 12-12 ngx_event_pipe_read_upstream 方 法 接收 上 游 响应 的 流程 


1) 检查 上 游 连 接 是 否 结束 ， 以 及 与 上 游 连 接 的 读 事 件 是 否 已 经 吕 
绪 ， 代 码 如 下 。 


// 这 


3 个 标志 位 的 意义 可 参见 


12.8.1 节 ， 其 中 任 一 个 为 


1 都 表示 上 游 连接 需要 结束 


if (p->upstream eof || p->upstream error || p->upstream done) { 


// 跳 到 第 


9 步 执行 


break; 


/* 如 果 读 事件 的 


ready 标 志 位 为 
0， 则 说 明 没有 上 游 响 应 可 以 接收 ; 


preread_bufs 预 读 缓冲 区 为 空 ， 表 示 接 收 包头 时 没有 收 到 包 体 ， 或 者 收 到 过 包 体 但 已 经 处 理 过 ] 


if (p->preread bufs == NULL && !p->upstream->read->ready) { 
// 跳 到 第 
9 步 执行 


break; 


如 采 这 两 个 条 件 有 一 个 满足 ， 则 和 需要 跳 到 第 9 步 ， 准 备 结 


ngX_event_pipe_read_upstream 方 法 ， 否 则 继续 执行 第 2 步 。 


2) 接收 上 游 响 应， 这 一 步 实 际 上 就 是 执行 图 12-11 中 列 出 的 7 个 步 
骤 。 它 会 导致 3 种 结果 : 4Q4) 如 果 free_raw_bufs 链 表 中 有 需要 处 理 的 包 
体 ， 则 跳 到 第 3 步 执行 ，Q@) 执 行 到 图 12-11 的 第 4 步 分 支 ， 


upstream_blocked 标 志 位 置 为 1， 同 时 ，ngx_event_pipe_read_upstream 方 
法 返回 NGX_OK; (3) 如 果 没 有 接收 到 包 体 ， 则 跳 到 第 8 步 执 行 。 


3) 置 read 标 志 位 为 1， 表 示 接 收 到 的 包 体 竺 处 理 。 
4) 从 接收 到 的 缓冲 区 链表 中 取出 一 块 ngx_buf t 绥 冲 区 。 


5) 调用 ngx_event_pipe_remove_shadow_links 方 法 将 这 块 缓冲 区 中 
的 shadow 域 释放 掉 ， 因 为 刚刚 接收 到 的 缓冲 区 ， 必 人 然 不 存在 多 次 引用 
的 情况 ， 所 以 shadow 成 员 要 指 癌 空 指 针 。 


6) 检查 本 次 读 取 到 的 包 体 是 否 大 于 或 等 于 绥 冲 区 的 剩余 空间 大 
小 。 这 一 步 的 意义 在 于 ， 如 采 当 前 接收 到 的 长 度 小 于 缓冲 区 长 度 ， 则 
说 明 这 个 缓冲 区 还 可 以 用 于 再 次 接收 啊 应 ， 这 时 跳 到 第 7 步 执 行 ， 否 
则 ， 这 个 缓冲 区 已 满 ， 则 应 该 调用 input_filter 方 法 处 理 ， 当 然 ， 默 认 的 
input_filter 方 法 就 是 ngx_event_pipe_copy_input_filter， 它 所 做 的 事情 就 
是 在 in 链 表 中 添加 这 个 缓冲 区 。 继 续 人 循环 执行 第 4 步 ， 遍 历 本 次 接收 到 
的 所 有 绥 冲 区 。 


7) 将 本 次 接收 到 的 缓冲 区 添加 到 free_raw_bufs 链 表 末 尾 ， 继 续 第 1 
步 执行 这 个 大 循环 。 


8) 将 upstream_eof 标 志 位 置 为 1， 表 示 上 游 服 务 器 已 经 关闭 了 连 
接 。 


9) 检查 upstream_eof 和 upstream_error 标 志 位 是 否 有 任意 一 个 为 1， 
如 果 有 ， 则 说 明 上 游 连 授 已 经 结束 ， 这 时 如 有 果 free_raw_bufs 绥 冲 区 链表 
不 为 空 ， 则 需要 跳 到 第 10 步 处 理 free_raw_bufs 中 的 缓冲 区 ， 否 则 返回 
NGX_OK， 结 束 ngx_event_pipe_read_upstream 方 法 。 


10) 再 次 调用 input_filter 方 法 处 理 free_raw_bufs 中 的 缓冲 区 (类 似 
第 6 步 ， 但 这 次 只 处 理 可 能 独 余 的 最 后 一 个 缓冲 区 ) 。 


11) 检查 free_bufs 标 志 人 位， 如果 free_bufs 为 1， 则 说 明 需 要 尽快 释 
放 缓 冲 区 中 用 到 的 内 存 ， 这 时 调用 ngx_pfree 方 法 释放 shadow 域 为 空 的 
缓冲 区 。 


可 以 看 到 ，ngx_event_pipe_read_upstream 方 法 将 会 把 接收 到 的 响应 
存放 到 内 存 或 者 磁盘 文件 中 ， 同 时 用 ngx_buf 缓冲 区 指向 这 些 响 应 ， 
最 后 用 in 和 out 缓 冲 区 链表 把 这 些 ngx_buf t 缓 冲 区 管理 起 来 。 图 12-12 只 
是 展示 了 ngx_event_pipe_read_upstream 方 法 的 主要 流程 ， 如 果 需 要 理解 
这 种 转发 时 缓冲 区 的 详细 用 法 ， 还 需要 对 照 着 图 12-11 和 图 12-12 来 阅读 
ngx_event_pipe.c 源 文件 。 


12.8.5 ngx_event_pipe_write_to_downstream 方 法 


ngx_event_pipe_write_to_downstream 方 法 负 员 把 in 链 表 和 out 链 表 中 
管理 的 缓冲 区 发 送 给 下 游客 户 问 ， 因 为 out 链 表 中 的 缓冲 区 内 容 在 啊 应 


中 的 位 置 要 比 in 链 表 更 靠 前 ， 所 以 out 需 要 优先 发 送 给 下 游 。 图 12-13 给 
出 了 ngx_event_pipe_write_to_downstream 方 法 的 流程 图 ， 这 个 流程 图 的 
核心 就 是 在 与 下 游 的 连接 事件 上 出 于 可 写 状态 时 ， 尽 可 能 地 循环 发 送 
out 和 in 链 表 绥 冲 区 中 的 内 容 ， 其 中 在 第 7、 第 8 步 中 还 会 涉及 shadow 域 
中 指向 的 缓冲 区 释放 的 问题 。 


下 面 详细 分 析 一 下 图 12-13 中 的 13 个 步骤 。 


1) 首先 检查 上 游 连接 是 否 结束 ， 判 断 依据 与 图 12-12 中 的 第 1 步 非 
常 相 似 ， 检 查 upstream_eof、upstream_error 还 有 upstream_done 标 志 位 ， 
任意 一 个 标志 位 为 1 都 表示 上 游 连接 不 会 再 收 到 啊 应 了， 这 时 跳 到 第 2 
步 执行 ， 否 则 继续 检查 与 下 游 连 接 的 写 事件 ready 标 志 位 ， 如 果 ready 为 
1， 表 示 可 以 向 下 游 发 送 响 应 ， 这 时 跳 到 第 5 步 执 行 ， 否 则 


ngx_event_pipe_write_to_downstream 方 法 结束 。 


2) 调用 output_filter 方 法 把 out 链 表 中 的 缓冲 区 发 送 到 下 游客 户 端 。 


3) 调用 output_filter 方 法 把 in 链表 中 的 缓冲 区 发 送 到 下 游客 户 端 。 


4) 将 downstream_done 标 志 位 置 为 1 (目前 没有 任何 意义 ) ， 


ngx_event_pipe_write_to_downstream 方 法 结 


5) 计算 busy 缓 冲 区 中 待 发 送 的 啊 应 长 度 ， 检 查 它 是 否 超 过 
busy_size 配 置 ， 如 果 其 大 于 或 等 于 busy_size， 则 跳 到 第 10 步 执行 ， 否 


则 继续 向 下 准备 发 送 out 或 者 in 绥 冲 区 中 的 内 容 。 也 就 是 说 ， 当 
ngx_http_request_t 结 构 体 中 out 绥 冲 区 中 的 待 改 送 内 容 已 经 超过 了 
busy_size， 就 跳 到 第 10 步 ， 不 再 发 送 out 和 ip 缓冲 区 中 的 内 容 ， 优 移 把 
ngx_http_request_t 结 构 体 的 out 中 的 内 容 发 送出 去 。 


6) 首先 检查 out 链 表 是 否 为 空 ， 如 果 out 中 有 内 容 ， 那 么 立刻 跳 到 
第 7 步 准备 发 送 out 绥 冲 区 中 的 啊 应 ， 如 琳 out 为 宇 ， 那 么 再 检查 in 链 表 。 
如 果 in 链 表 中 有 内 容 ， 立 刻 跳 到 第 8 步 准 备 发 送 in 绥 冲 区 中 的 响应 ， 如 
果 in 链 表 也 为 空 ， 则 说 明 这 次 调用 中 没有 和 需要 发 送 的 响应 ， 跳 到 第 10 步 
1 


7) 取出 out 链 表 首 部 的 第 一 个 ngx_buf t 绥 冲 区 ， 检 查 待 发 送 的 长 
度 加 上 这 个 缓冲 区 后 是 否 已 经 超过 busy_size 配 置 ， 如 果 超 过 ， 则 立刻 
跳 到 第 10 步 执行 ， 如 果 没 有 超过 ， 则 out 目 动 指向 链表 中 的 下 一 个 
ngx_chain_t 元 素 ， 跳 到 第 9 步 准备 将 之 前 取出 的 第 一 个 缓冲 区 发 送出 
去 。 注 意 ， 这 里 还 会 调用 ngx_event_pipe_free_shadow_raw_buf 方 法 来 处 
理 这 个 待 发 送 的 缓冲 区 的 shadow 域 ,实际 上 ， 这 一 步 就 是 为 了 释放 
free_raw_bufs 链 表 中 的 缓冲 区 。 


i 


[上 游 连接 已 经 结 ? 


[上 游 连接 未 结束 ] 


[ 写 事件 准备 好 ] 
朗 名 区 天水 


[busy 绥 冲 区 未 超过 busy_sizel 


2) 回 下 洲 发 送 
out 组 冲 区 


3) 回 下 洲 发 送 
in 组 冲 区 


4 ) 设 置 downstream_down 
标志 位 为 1 


6) 检 测 out 和 in 
缓冲 区 链表 
[busy 绥 冲 区 超过 busy_sizel 


[in 链表 不 为 空 ] 


[in、 out 链表 为 空 
或 待 发 送 内 容 超过 


busy_size] 


[out 链表 不 为 空 ] 


7) 使 用 out 链表 首 个 绥 冲 区 
作为 发 送 内 容 
[ 写 事件 未 准备 好 ] 


8) 使 用 in 链表 首 了 人 
缓冲 区 作为 发 送 内 容 


9) 将 刚 处 理 的 buf 
设置 到 out 链 表 


10) 检查 out 绥 冲 区 以 及 之 前 各 步 又 
是 否 有 内 容 需 要 发 


[没有 需要 发 送 的 内 容 ] 
[有 内 容 需 要 发 送 ] 


11) 调 用 output_filter 
发 送 啊 应 


12) 调 用 ngx_chain _update_chains 
方法 更 新 缓冲 区 


13) 释 放 free 
链表 中 的 缓冲 区 @ 


图 12-13 ngx_event_pipe_write_to_downstream 方 法 的 流程 图 


8) 取出 in 链 表 首 部 的 第 一 个 缓冲 区 准备 发 送 ， 所 有 步 又 与 第 7 步 相 


9) 将 刚才 调用 ngx_event_pipe_free_shadow_raw_buf 方 法 处 理 过 的 
缓冲 区 再 添加 到 out 链 表 首 部 〈 竺 发 送 的 内 容 都 添加 到 out 绥 冲 区 链表 中 
了 ) ， 同 时 跳 到 第 6 步 继续 执行 这 个 循环 。 


10) 检查 out 链 表 以 及 之 前 各 个 步骤 中 是 否 有 需要 发 送 的 内 容 (其 
是 通过 一 个 局 部 变量 flush 作 为 标志 位 来 表示 是 否 有 需要 发 送 的 内 
) ， 当 out 为 空 且 确 实 没 有 待 发 送 的 内 容 时 ， 返 回 NGX_OK， 
ngx_event_pipe_write_to_downstream 方 法 结束 ， 否 则 跳 到 第 11 步 同 下 游 
发 送 响应 。 


11) 调用 output_filter 方 法 向 下 游 发 送 out 缓 冲 区 。 


12) 调用 ngx_chain_update_chains 方 法 更 新 free、busy、out 缕 冲 
区 。 在 图 12-8 的 第 4 步 中 曾经 介绍 过 该 方法 ， 不 再 玖 述 。 


13) 遍历 free 链 表 中 的 缓 促 区 ， 释 放 绥 促 区 中 的 shadow 域 ， 这 样 ， 
这 些 暂 不 使 用 的 缓冲 区 才 可 以 继续 用 来 接收 新 的 来 自 上 游 服务 器 的 啊 
应 。 然 后 ， 跳 到 第 1 步 继续 发 送 啊 应 来 执行 这 个 大 循环 。 


至 此 ，buffering 配 置 为 1 时 转发 上 游 响 应 到 下 游 的 整个 流程 束 全 首 
介绍 完了 ， 它 的 流程 复杂 ， 但 效率 很 高 ， 作 为 反 向 代理 使 用 非常 有 优 
势 。 


12.9 结束 upstream 请 求 


当 Nginx 写 上 游 服 务 右 的 交互 出 错 ， 或 者 正常 处 理 完 来 自 上 洲 的 响 
应 时 ， 束 需要 结束 请 求 了 。 这 时 当然 不 能 调用 第 11 半 中 介绍 的 
ngx_http_finalize_request 方 法 来 结束 请 求 ， 这 样 upstream 中 使 用 到 的 资 
源 (如 与 上 游 间 建立 的 TCP 连 接 ) 将 无 法 释放 ， 事 实 上 ，upstream 机 制 
提供 了 一 个 类 似 的 方法 ngx_http_upstream_finalize_request 用 于 结 
upstream 请 求 ， 在 12.9.1 节 中 将 会 详细 介绍 这 个 方法 。 除 了 直接 调用 
ngx_http_upstream_finalize_request 方 法 结束 请 求 以 外 ， 还 有 两 种 独特 
的 结束 请 求 方法 ， 分 别 是 ngx_http_upstream_cleanup 方 法 和 


ngx_http_upstream_next 方 法 。 


在 启动 upstream 机 制 时 ，ngx_http_upstream_cleanup 方 法 会 挂 载 到 
请 求 的 cleanup 链 表 中 (参见 图 12-2 的 第 3 步 ) ， 这 样 ，HTTP 框 架 在 请 
求 结束 时 束 会 调用 ngx_http_upstream_cleanup 方 法 (参见 11.10.2 廊 
ngx_http_free_request 方 法 的 流程 ) ， 这 保证 了 
ngx_http_upstream_cleanup 一 定 会 被 调用 。 而 
ngx_http_upstream_cleanup 方 法 实际 上 还 是 通过 调用 
ngx_http_upstream_finalize_request 来 结束 请 求 的 ， 如 下 所 示 。 


static void ngx_http_upstream cleanup(void *data) 


ngx_http_request_t *r = data; 


ngx_http_upstream t *u = r->upstream; 


/* 最 终 还 是 调 


ngx_http_upstream_finalize_request 方 法 来 结束 请 求 ， 注 意 传 递 的 是 
NGX_DONE 参 数 


*/ 
ngx_http_upstream_finalize_request(r, u, NGX_DONE) ， 


当 处 理 请 求 的 流程 中 出 现 错误 时 ， 往 往 会 调用 
ee 。 例如 ， 在 图 12-5 中 ， 如 有 果 在 接收 上 游 服 
恬 的 包头 时 出 现 错误 ， 接 下 来 就 会 调用 该 方法 ， 这 是 因为 upstream 
机 制 还 提供 了 一 个 较为 灵活 的 功能 ， 当 与 上 游 的 交互 出 现 错误 时 ， 
Nginx 并 不 想 立 刻 认为 这 个 请 求 处 理 失败 ， 而 是 试图 多 给 上 游 服 务 
些 机 会 ， 可 以 重新 向 这 人 台 或 者 另 一 台 上 游 服务 器 发 起 连接 、 发 送 请 
求 、 接 收 响应 ， 以 避免 网 络 故障 。 这 个 功能 可 以 帮助 HITP 模 块 实现 简 
单 的 负载 均衡 机 制 (如 最 常见 的 HTTP 反 向 代理 模块 ) 。 而 该 功能 正 是 
通过 ngx_http_upstream_next 方 法 实现 的 ， 因 为 该 方法 在 结束 请 求 之 
前 ， 0 (参见 9.3.2 节 ) 。 
tries 成 员 会 初始 化 为 每 个 连接 的 最 大 重 试 次 数 ， 每 当 这 个 连接 与 上 游 
服务 器 出 现 错误 时 就 会 把 tries 减 1。 在 出 错时 ngx_http_upstream_next 方 
法 首先 会 检查 tries， 如 果 它 减 到 0， 才 会 真正 地 调用 
ngx_http_upstream_finalize_request 方 法 结束 请 求 ， 否 则 不 会 结束 请 
求 ， 而 是 调用 ngx_http_upstream_connect 方 法 重新 向 上 游 发 起 请 求 ， 如 
下 所 示 。 


static void ngx_http_upstream next(ngx_http_request t *r, ngx_http_upstream t *u, 
ngx_uint_t ft_type) 
{ 


/* 只 有 向 这 台 上 游 服务 器 的 重 试 次 数 


tries 减 为 
0 时 ， 才 会 真正 地 调 


ngx_http_upstream_finalize_request 方 法 结束 请 求 ， 否 则 会 再 次 试图 重新 与 上 游 服 务 器 交互 ， 这 个 功 
能 将 帮助 感 兴趣 的 


HTTP 模 块 实现 简单 的 负载 均衡 机 制 。 


uU->conf->next_upstream 表 示 的 含义 在 


12.1.3 节 中 已 介绍 过 ， 它 实际 上 是 一 个 


本 
hulll 
ph 
泪 


32 位 的 错误 码 组 合 ， 表 示 当 出 现 这 些 错 误 码 时 不 能 直接 结束 请 求 ， 需 要 向 下 一 台 上 游 服务 器 再 


< 
if (u->peer.tries == 0 || !(u->conf->next_upstream & ft_type)) 


ngx_http_upstream_ finalize_request(r, u, status); 
return; 


} 
// 如 果 与 上 游 间 的 


TCP 连 接 还 存在 ， 那 么 需要 关闭 


if (u->peer.connection) { 
ngx_close_connection(u->peer.connection); 
Uu->peer .connection = NULL; 


// 重新 发 起 连接 ， 参 见 


12 .3 节 


ngx_http_upstream connect(r, u); 
下 面 来 看 一 下 ngx_http_upstream_finalize_request 到 底 做 了 些 什 么 


工作 。 


ngx_http_upstream_finalize_request 方 法 还 是 会 通过 调用 HTTP 框 架 
提供 的 ngx_http_finalize_request 方 法 释放 请 求 ， 但 在 这 之 前 需要 释放 与 


上 游 交 互 时 分 配 的 资源 ， 如 文件 句柄 、TCP 连 接 等 。 它 的 源 代码 很 简 
单 ， 下 面 直 接 列 举 其 产 代 码 说 明 它 所 做 的 工作 。 


static void ngx_http_upstream finalize request(ngx_http_request _t *r, 
ngx_http_upstream t *u, ngx_int_t rc) 
{ 


ngx_time t *tp; 
// 将 


cleanup 指 向 的 清理 资源 回调 方法 置 为 
NULL 空 指针 
if (u->cleanup) { 
*Uu->cleanup = NULL; 


uU->cleanup = NULL; 


} 
// 释放 解析 主机 域名 时 分 配 的 资源 


If (u->resolved && u->resolved->ctx) { 
ngx_resolve_name_done(u->resolved->ctx); 
U->resolved->ctx = NULL 


if (u->state && U->State->reSsponse_Ssec) { 


// 设置 当前 时 间 为 


HTTP 响 应 结束 时 间 


tp = ngx_timeofday()， 
U->state->response_sec = tp->sec - U->state->response_sec; 
U->State->response_msec = tp->msec - U->State->reSsponse_msec 
if (u->pipe) { 

Uu->state->response_ length = u->pipe->read length,; 


} | 
/* 表 示 调 


HTTP 模 块 负责 实现 的 


finalize_request 方 法 。 


HTTP 模 块 可 能 会 在 


upstream 请 求 结束 时 执行 一 些 操作 


U->finalize_request(r，rc)， 
/* 如 果 使 用 了 
TCP 连 接 池 实现 了 


free 方 法 ， 那 么 调 


free 方 法 (如 


ngx_http_upstream_free_round_robin_peer) 释放 连接 资源 


if (u->peer.free) { 
U->peer.free(&u->peer, u->peer.data, 0); 
} 
// 如 果 与 上 游 间 的 
TCP 连 接 还 存在 ， 则 关闭 这 个 
TCP 连 接 
if (u->peer.connection) { 
ngx_close_connection(u->peer.connection); 
} 
Uu->peer .connection = NULL; 
If (u->store && U->pipe && U->pipe->temp_file 
&& U->pipe->temp_file->file.fd != NGX_INVALID_FILE) 
/* 如 果 使 用 了 磁盘 文件 作为 缓存 来 向 下 游 转发 响应 ， 则 需要 删除 用 于 缓存 响应 的 临时 文件 


if (ngx_delete file(u->pipe->temp_file->file.name.data) 


== NGX_FILE_ERROR) 
{ 
ngx_log_error(NGX_LOG_CRIT, r->connection->log, ngx_errno, 
ngx_delete file n " \"%s\" failed", 
uU->pipe->temp_file->file.name.data); 
} 
} 
/* 如 果 已 经 向 下 游客 户 端 发 送 了 


HTTP 响 应 头 部 ， 却 出 现 了 错误 ， 那 么 将 会 通过 下 面 的 


ngx_http_send_special(r，NGX_HTTP_LAST) 将 头 部 全 部 发 送 完毕 


If (u->header_sent && rc != NGX_HTTP_REQUEST_TIME_OUT 
&& (rc == NGX_ERROR || rc >= NGX_HTTP_SPECIAL_RESPONSE ) ) 
{ 
rc = 0; 
} 
if (rc == NGX_DECLINED) { 
return; 
} 
r->connection->l0g->action = "sending to client"; 
if (rc == 0) 
{ 
rc = ngx_http_send_special(r, NGX_HTTP_LAST); 
} 
/* 最 后 还 是 通过 调 
HTTP 框 架 提 供 的 


ngx_http_finalize_request 方 法 来 结束 请 求 


4 


ngx_http_finalize_request(r, rc); 


1210， 才 第 


本 章 介 绍 的 upstream 机 制 也 属于 HTTP 框 架 的 一 部 分 ， 它 同样 是 基 
于 事件 框 染 实现 了 异步 访问 上 游 服务 妖 的 功能 ， 同 时 ， 它 并 不 满足 于 
仅仅 帮助 应 用 级 别 的 HTTP 模 块 基于 TCP 访 问 上 游 ， 而 是 提供 了 非常 强 
大 的 转发 上 游 响 应 功能 ， 而 且 在 转发 方式 上 更 加 灵活 、 高 效 ， 并 且 对 
于 内 存 的 使 用 相当 市 省 ， 这 些 功能 帮助 Nginx 的 ngx_http_proxy_module 
模块 实现 了 强大 的 反 向 代理 功能 。 同 时 ， 配 合 着 
ngx_http_upstream_ip_hash_module 或 者 Round Robin 相 关 的 代码 (它们 


负责 管理 ngx_peer_connection_t 上 游 连接 ) ，ngx_http_upstream_next 方 


法 还 可 以 帮助 HTTP 模 块 实现 简单 的 负载 均衡 功能 。 


由 于 upstream 机 制 属于 HTTP 框 架 ， 所 以 它 仅 抽象 出 了 通用 代码 ， 
而 尽量 地 把 组 闭 发 往 上 游 请 求 、 解 析 上 游 响 应 的 部 分 都 交 给 使 用 它 的 
HTTP 模 块 实现 ， 这 使 得 使 用 upstream 的 HTTP 模 块 不 会 太 复杂 ， 而 性 
却 非 常 高 效 ， 算 是 在 灵活 性 和 简单 性 之 间 找 到 了 一 个 平衡 点 。 在 阅 
读 完 本 章 后 ， 我 们 就 有 可 能 写 出 非常 强大 的 访问 第 三 方 服务 器 的 代码 
了 ， 在 这 个 过 程 中 ， 尽 量 使 用 upstream 已 经 提供 的 各 种 功能 ， 将 会 简 
化 HITP 模 块 的 开发 过 程 。 


IO 
EE 


站 


第 13 章 ”邮件 代理 模块 


本 章 将 说 明 Nginx 官 方 提 供 的 一 系列 邮件 模块 ， 这 些 邮 件 模块 配合 
Nginx 事 件 框 架 共 同 构建 了 支持 POP3、SMTP、IMAP 这 3 种 协议 的 邮件 
代理 服务 器 ， 它 们 把 邮件 代理 服务 器 的 主要 功能 抽象 成 一 个 类 似 于 
HTTP 框 染 的 邮件 框架 ， 以 灵活 地 支持 Nginx 扩 展 更 多 的 邮件 协议 ， 而 
POP3、SMTP、IMAP 模 块 将 作为 普通 的 邮件 模块 使 用 这 套 框 架 。 作 为 
邮件 代理 服务 器 的 Nginx 虽 然 也 访问 上 游 服务 器 ， 但 由 于 它 不 使 用 
HTTP 框 架 ， 所 以 无 法 使 用 第 12 章 介绍 的 upstream 机 制 ， 然 而 “邮件 代 
理 ” 其 实 同 样 具有 部 分 的 反 向 代理 功能 ， 本 章 13.7 节 介绍 的 透 传 TCP 部 
分 其 实 也 有 点 像 一 个 简化 版 的 upstream 机 制 。 


本 章 首先 介 绍 邮 件 代理 功能 到 底 做 了 哪些 事情 ， 接 下 来 会 分 析 
Nginx 如 何 实现 邮件 代理 功能 。 实 际 上 ， 本 章 更 像 是 第 10 章 ~ 第 12 章 的 
简化 版 本 ， 所 以 在 本 章 中 将 不 会 再 次 描述 曾经 介绍 过 的 如 何 异步 地 、 
无 阻塞 地 提供 服务 ， 以 及 如 何 使 用 epoll、 定 时 器 等 事件 框架 。 读 者 也 
应 当 熟 悉 Nginx 的 这 套 设计 方法 了 ， 因 此 本 章 仅 会 指 述 邮件 模块 的 主要 
阶段 ， 不 会 深入 细节 。 另 外 ， 本 章 也 不 会 详细 说 明 POP3、SMTP、 
IMAP， 因 为 Nginx 并 非 真正 的 邮件 服务 狠 。 本 章 的 重点 在 于 了 解 邮件 
代理 服务 器 的 使 用 方法 ， 以 及 应 该 如 何 扩展 邮件 代理 模块 的 功能 ， 同 


时 了 解 通过 邮件 模块 继续 熟悉 Nginx 事 件 框架 的 用 法 ， 继 而 熟悉 如 何 利 
用 它 开发 高 性 能 服务 器 。 


13.1 ”邮件 代理 服务 器 的 功能 


在 第 8 章 中 介绍 过 邮件 模块 ， 它 提供 了 邮件 代理 服务 器 的 功能 。 什 
么 是 邮件 代理 服务 器 ? 顾名思义 ， 它 不 会 提供 实际 的 邮件 服务 器 功 
能 ， 而 是 把 客户 端的 请 求 代理 到 上 洲 的 邮件 服务 如 中。 那么 ， 客 户 端 
为 何不 直接 访问 真正 的 邮件 服务 器 ， 反 而 多 此 一 举 地 访问 邮件 代理 服 
务 器 呢 ? 原因 可 以 在 后 续 章 节 描 述 的 Nginx 实 现 中 找到 ， 其 中 最 重要 的 
是 Nginx 并 不 是 简单 地 透 传 邮件 协议 到 上 游 ， 它 还 有 一 个 认证 的 过 程 ， 
如 图 13-1 所 示 。 


从 图 13-1 中 可 以 看 出 ，Nginx 在 与 下 游客 户 问 交互 过 程 中 ， 还 会 访 
问 认 证 服务 器 ， 只 有 认证 服务 句 通 过 了 并 且 被 告知 Nginx 上 游 的 邮件 服 
务 右 地 址 后 ，Nginx 才 会 同上 游 的 邮件 服务 右 发 起 通信 请 求 。 同 时 ， 
Nginx 可 以 解析 客户 问 的 协议 获得 必要 的 信息 ， 接 下 来 它 还 可 以 根据 客 
户 闪 发 来 的 信息 快速 、 独 立地 与 邮件 服务 器 做 简单 的 认证 交互 ， 之 后 
才 会 开始 在 上 、 下 游 之 间 透 传 TCP 流 。 这 些 行为 都 意味 着 Nginx 的 高 并 
发 特性 将 会 降低 上 游 邮 件 服务 器 的 并 发 压力 。 


了 


POP3 邮 件 服 务 需 了 务 器 SMTP 邮件 服 


Neinx HTTP 认 证 服务 谷 


L 


邮件 客户 闹 


图 13-1 Nginx 在 邮件 代理 场景 中 的 位 置 


Nginx 与 下 游客 户 端 、 上 游 邮 件 服务 器 间 都 是 使 用 邮件 协议 ， 而 与 
认证 服务 器 之 间 却 是 通过 类 似 HTTP 的 形式 进行 通信 的 。 例 如 ， 发 往 认 
证 服务 器 的 请 求 如 下 所 示 : 


GET /auth HTTP/1.0 

Host: auth.server.hostname 
Auth-Method: plain 
Auth-User: user 

Auth-Pass: password 
Auth-Protocol: imap 
Auth-Login-Attempt: 1 
Client-IP: 192.168.1.1 


而 认证 服务 夯 会 返回 最 音 见 的 成 功 啊 应 ， 即 类 似 下 面 的 字符 流 : 


HTTP/1.0 200 OK 
Auth-Status: OK 
Auth-Server: 192.168.1.10 
Auth-Port: 110 

Auth-User: newname 


当然 ， 认 证 服务 器 的 返回 要 复杂 得 多 。 由 于 本 章 既 不 会 介绍 认证 
服务 器 如 何 实现 ， 也 不 会 介绍 上 游 的 邮件 服务 器 如 何 实 现 ， 所 以 对 协 
义 部 分 不 会 继续 深入 介绍 。 


一 般 情况 下 ， 客 户 端 发 起 的 邮件 请 求 在 经 过 Nginx 这 个 邮件 代理 服 
务 器 后 ， 网 络 通 信 过 程 如 图 13-2 所 示 。 


从 网 络 通信 的 角度 来 看 ，Nginx 实 现 邮 件 代理 功能 时 会 把 一 个 请 求 
分 为 以 下 4 个 阶段 。 


-接收 并 解析 客户 端 初始 请 求 的 阶段 。 


` 回 认 证 服务 右 验 证 请 求 合 法 性 ， 并 获取 上 游 邮 件 服务 絮 地 址 的 阶 


"Nginx 根 据 用 户 信息 多 次 与 上 游 邮 件 服务 器 交互 验证 合法 性 的 阶 


"Nginx 在 客户 剖 与 上 游 邮 件 服务 紫 间 纯粹 透 传 TCP 流 的 阶段 。 


由 此 可 以 了 解 到 ， 这 些 Nginx 邮 件 模 块 的 目的 非常 明确 ， 束 古 使 用 
事件 框架 在 大 量 并 发 连接 下 高 效 地 处 理 这 4 个 阶段 的 请 求 。 


游客 户 端 Nginx 了 出 邮件 服务 器 
re 。 [ii 


| 用 户 请 求 | 


1 
1 
| 
类 HTTP 认 证 请 求 | 


认证 啊 应 


1 
发 起 TCP 连 接 


欢迎 消息 


验证 用 户 名 、 密 码 等 


POP3、 
SMTP、IMAP 
等 协议 需要 响应 
交互 的 次 数 | | 
都 不 相同 


转发 上 游 的 啊 应 


Nginx 将 开始 在 
客户 端 与 邮件 服 
务 器 之 间 双 向 透 
传 TCP 流 


转发 上 游 的 请 求 
啊 应 


图 13-2 ”邮件 代理 功能 的 示意 序列 图 


为 了 让 读者 对 邮件 代理 服务 器 有 直观 的 认识 ， 下 面 再 来 看 看 
nginx.conf 配 置 文件 。 邮 件 模块 定义 的 nginx.conf 配 置 文件 与 HITP 模 块 
非常 相似 。 例 如， 香 见 的 配置 可 能 束 像 下 面 的 这 段 配置 一 样 。 


mail { 
// 邮件 认证 服务 器 的 访问 


URL 
auth_http IP:PORT/auth.php; 
// 当 透 传 上 、 下 游 间 的 


TCP 流 时 ， 每 个 请 求 所 使 用 的 内 存 缓冲 区 大 小 


proxy_buffer 4k; 
server { 
/* 对 于 


POP3 协 议 ， 通常 都 是 监听 


110 端 口 。 


POP3 协 议 接收 初始 客户 端 请 求 的 缓冲 区 固定 为 


128 字 节 ， 配 置 文件 中 无 法 设置 


*/ 
listen 110; 
protocol pop3,; 


proxy on; 
} 
server { 

// 对 于 


IMAP， 通 常 都 是 监听 


143 端 口 


listen 143 
protocol imap; 


// 设置 接收 初始 客户 端 请 求 的 缓冲 


imap_client_buffer 4k; 
proxy on; 


server { 


// 对 于 


SMTP， 通 常 都 是 监听 


| 


25 端 口 
listen 25， 
protocol smtp; 
proxy on,; 
// 设置 接收 初始 客户 端 请 求 的 缓 六 
smtp_client_buffer 4k; 
} 


mail{} 块 下 的 配置 项 将 会 被 本 章 介绍 的 邮件 模块 所 使 用 。 就 像 
HTTP 模 块 中 的 配置 一 样 ， 直 属于 mail{} 块 下 的 配置 称 为 main 级 别 的 配 
置 ， 而 在 server{} 块 下 的 配置 则 称 为 svr 配 置 (不 使 用 HTTP， 故 没有 loc 
级 别 的 配置 ) 。 


13.2 ”邮件 模块 的 处 理 框 淋 


本 广 首 先 会 从 总 体 上 说 明 邮 件 框架 是 如 何 处 理 请 求 的 ， 接 着 会 介 
绍 这 一 新 的 模块 类 型 有 什么 样 的 接口 ， 以 及 应 当 如 何 定义 ， 最 后 将 会 
人 简单 地 说 明 邮 件 框 架 的 初始 化 过 程 。 


13.2.1 一 个 请 求 的 8 个 独立 处 理 阶 段 


图 13-2 大 致 介绍 了 请 求 的 处 理 过 程 ， 而 对 于 邮件 框架 而 言 ， 通 肖 
可 以 把 请 求 的 处 理 过 程 分 为 8 个 阶段 。 这 里 “阶段 ”的 划分 依据 是 什么 
呢 ? 由 于 Nginx 是 异步 的 、 非 阻塞 的 处 理 方式 ， 所 有 仙 贡 独立 功能 的 一 
个 (或 者 几 个 ) 方法 可 能 被 epoll 或 者 定时 器 无 数 次 地 驱动 、 调 度 ， 政 
而 可 以 把 相同 代码 可 能 被 反复 多 次 调用 的 过 程 称 为 一 个 阶段 。 下面 按 
照 这 种 划分 方式 ， 把 请 求 分 为 8 个 阶段 ， 如 图 13-3 所 示 。 


1) 初 始 化 邮件 
请 求 
2 ) 接 收 并 解析 客户 
端 请 求 阶段 
连接 阶段 


3 ) 向 认证 服务 器 发 起 
TCP 连接 阶段 


4) 向 认证 服务 器 发 送 


请 求 阶段 


5 ) 接 收 并 解析 认证 服务 右 
的 响应 阶段 


6) 回 上 游 邮 件 服务 大 
发 起 连接 阶段 


7) 与 邮件 服务 器 交互 
已 知 信息 阶段 


8) 双向 透 传 下 游客 户 端 与 上 游 


邮件 服务 右 的 内 容 


图 13-3 ”邮件 框架 中 处 理 一 个 请 求 的 主要 阶段 
这 8 个 阶段 必须 依次 向 下 进行 ， 它 们 的 意义 如 下 。 


1) 当 客 户 端 发 起 的 TCP 连 接 建 立成 功 时 ， 就 会 回调 邮件 框架 初始 
化 时 设 定 的 ngx_mail_init_connection 方 法 ， 在 这 个 方法 中 会 初始 化 将 要 
用 到 的 数据 结构 ， 并 设置 下 一 个 阶段 的 处 理 方法 。 


2) 接收 、 解 析 客 户 端的 请 求 。 这 个 阶段 会 读 取 客 户 端 发 来 的 TCP 
流 ， 并 使 用 状态 机 解析 它 ， 如 果 解 析 后 发 现 已 接收 到 完整 的 请 求 ， 则 
进入 下 一 阶段 ， 否 则 ， 将 会 继续 把 连接 上 的 读 事件 添加 到 epoll 中 ， 并 
等 得 epoll 的 下 一 次 调度 ， 以 便 继续 读 取 客户 剖 请 求 。 


3) 解析 到 完整 的 请 求 后 ， 就 需要 向 认证 服务 器 发 起 类 似 HTTP 的 
请 求 来 验证 请 求 是 否 合 法 。Nginx 与 认证 服务 絮 间 仍然 是 通过 TCP 通 信 
的 ， 发 起 三 次 握手 目 然 算是 一 个 独立 的 阶段 。 


4) 当 Nginx 与 认证 服务 器 成 功 建立 TCP 连 接 时 ， 
ngx_mail_auth_http_module 模 块 将 会 构造 、 发 送 请 求 到 认证 服务 器 。 
在 13.4.3 节 中 将 要 介绍 的 ngx_mail_auth_http_write_handler 方 法 会 确保 
全 部 的 请 求 都 发 送 到 认证 服务 器 中 。 


5) Nginx 接 收 认 证 服务 器 的 响应 是 通过 
ngx_mail_auth_http_read_handler 完 成 的 ， 在 该 方法 中 ， 每 接收 一 部 分 


咖 应 都 要 使 用 状态 机 来 解析 ， 在 接收 完整 的 啊 应 (包括 啊 应 行 和 HTTP 
头 部 ) 后 ， 还 会 分 析 啊 应 结果 以 确定 请 求 是 否 合法 ， 如 果 合 法 ， 将 继 
续 执 行 下 一 阶段 。 


6) 这 一 阶段 将 从 认证 服务 器 返回 的 响应 中 获得 上 游 邮 件 服务 器 的 
地 址 ， 接 着 向 上 游 邮 件 服务 器 发 起 TCP 连 接 。 


7) 在 TCP 连 接 建立 成 功 后 ， 接 下 来 是 Nginx 与 邮件 服务 器 使 用 
POP3、SMTP 或 者 IMAP 交 互 的 阶段 。 这 一 过 程 主要 是 Nginx 将 请 求 中 
的 用 户 、 密 码 、 发 件 人 、 收 件 人 等 信息 传递 给 邮件 服务 器 ， 这 个 过 程 
是 双 同 的 ， 直 到 Nginx 认 为 邮件 服务 如 同意 继续 向 下 进行 时 ， 才 会 继续 
下 一 阶段 。 


8) 这 一 阶段 是 最 主要 的 透 传 邮件 协议 阶段 。 只 要 Nginx 收 到 下 游 
客户 端的 TCP 流 【无论 是 哪 一 种 邮件 协议 ， 会 原封 不 动 地 转发 给 上 
游 的 邮件 服务 器 ， 同 样 ， 如 末 收 到 上 游 的 TCP 流 ， 也 会 原样 转发 给 下 


游 。 


邮件 框架 的 目标 就 是 健壮 、 高 效 地 处 理 这 8 个 阶段 。 


13.2.2 ”邮件 类 模块 的 定义 


在 第 8 章 说 过 ， 每 一 个 Nginx 模 块 都 会 使 用 ngx_module_t 结 构 体 来 
表示 ， 而 ngx_module_t 中 的 ctx 成 员 将 指向 各 种 模块 的 特有 接口 。 


首先 介绍 的 邮件 模块 是 NGX_CORE_MODULE 类 型 的 
ngx_mail module 模 块 ， 它 定义 了 一 种 新 的 模块 类 型 ， 叫 做 
NGX_MAIL_MODULE。 同 时 ， 它 会 管理 所 有 NGX_MAIL_MODULE 
类 型 的 邮件 模块 。 这 些 邮 件 模块 的 ctx 成 员 指 向 的 抽象 接口 叫做 
ngx_mail module t， 如 下 所 示 。 


typedef struct { 
// POP3、 


SMTP、 


IMAP 邮 件 模块 提取 出 的 通用 接 


ngx_mail_ protocol t *protocol; 
/* 创 建 用 于 存储 


main 级 别 配 置 项 的 结构 体 ， 该 结构 体 中 的 成 员 将 保存 直属 于 
mailf{} 块 的 配置 项 参数 


void *(*create main_conf)(ngx_conf_t *cf); 
/* 解 析 完 


main 级 别 配置 项 后 被 回调 


eA 
char *(*init_main_conf)(ngx_conf_t *cf, void *conf); 
/* 创 建 用 于 存储 

srv 级 别 配 置 项 的 结构 体 ， 该 结构 体 中 的 成 员 将 保存 直属 


server{} 块 的 配置 项 参数 


2 
void *(*create_ srv_conf)(ngx_conf_t *cf)， 


/*svr 级 别 可 能 存在 与 
main 级 别 同名 的 配置 项 ， 该 回调 方法 会 给 具体 的 邮件 模块 提供 一 个 手段 ， 以 便 从 


prev 和 


conf 参 数 中 获取 到 


main 和 


已 经 解析 完毕 的 


Srv 配 


人 


项 结构 体 ， 


由 地 重新 修改 它们 的 值 


char *(*merge_srv_conf)(ngx_conf_t *cf, void *prev, void *conf); 
} ngx_mail module_t; 


一 个 邮件 模块 都 会 实现 ngx_mail module _t 接 口 。 除 了 最 上 面 的 
protocol 成 员 以 外 ， 其 实 ngx_mail module_t 与 ngx_http_module_t 非 常 相 
似 ， 当 然 ， 那 些 同 名 成 员 的 功能 也 是 相似 的 。 下 面 看 一 下 这 个 protocol 
接口 定义 了 哪些 内 容 。 


typedef struct ngx_mail_protocol s ngx_mail_protocol t,; 


// 4 个 
POP3、 


SMTP、 


IMAP 等 应 用 级 别 的 


邮件 模块 所 要 实现 的 接 


方法 


typedef void (*ngx_mail init_ session pt)(ngx mail] session t *s, 
ngx_connection t *c),; 

typedef void (*ngx_mail_init_protocol_pt)(ngx_event_t *rev); 

typedef void (*ngx_mai]l_auth_state_pt)(ngx_event_t *rev); 

typedef ngx_int t (*ngx_mail parse command_pt) (ngx_mail_session t *s); 

struct ngx_mail protocol s { 


// 邮件 模块 名 称 


ngx_str_t name 


A 


4 个 端 


in_port_t 


/* 


当前 邮件 模块 中 所 要 监听 的 最 党 


port[4]; 


b 件 模块 类 型 。 目 前 


type 仅 可 以 取 值 为 : 


NGX_MAIL_POP3_PROTOCOL、 


NGX_MAIL_IMAP_PROTOCOL、 


NGX_MAIL_SMTP_PROTOCOL*/ 
ngx_uint_t type; 


的 


// 与 客户 端 建立 起 
TCP 连 接 后 的 初始 化 方法 


ngx_mail_ init_session_pt init_session,; 


// 接收 、 解 析 客 户 端 请 求 的 方法 


ngx_mail_ init_protocol pt init_protocol; 
// 解析 客户 端 邮件 协议 的 接口 方法 ， 


POP3、 


SMTP、 


IMAP 等 邮件 模块 实现 


ngx_mail_parse_command_pt parse_command ; 


// 认证 客户 端 请 求 的 方法 


ngx_mail_auth_state_pt auth_state 
/* 当 处 理 过 程 中 出 现 没有 预见 到 的 错误 时 ， 将 会 返回 


internal_server_error 指 定 的 响应 到 客户 端 
*/ 
| ngx_str_t internal_server_error,; 
可 以 看 到 ，ngx_mail_protocol t 接 口 定 义 了 POP3、SMTP、IMAP 
等 应 用 级 别 的 邮件 模块 加 入 到 邮件 框 染 时 所 要 实现 的 接口 以 及 需要 遵 


循 的 规则 。 


关于 POP3、SMTP、IMAP 模 块 的 定义 ， 这 里 不 再 介绍 ， 读 者 可 以 
自行 查看 Nginx 源 代码 。 在 下 面 的 章节 中 ， 读 者 将 看 到 它们 如 何 结合 邮 
件 框架 来 实现 邮件 代理 功能 


13.2.3 ”邮件 框架 的 初始 化 


当 nginx.conf 文 件 中 出 现 mail{} 或 者 imap{} 配 置 项 时 ， 
n gxX_mail_module 模 块 就 从 ngx_mail_block 方 法 开始 它 的 初始 化 过 程 
(与 第 10 章 中 的 HTTP 框 架 非 常 相似 ) ， 如 图 13-4 所 示 。 


初始 化 每 一 个 邮件 模块 的 
ctx_index 序 号 


分 配 存放 main 级 别 配置 项 、svr 
级 别 配 置 项 指针 的 两 个 指针 数组 


调用 所 有 邮件 模块 的 create_main_conf 
方法 创建 存放 main 配 置 项 的 结构 体 


调用 所 crv_cont 
从 svT 级 页 的 疆 
ee | server{} 
继续 解析 svr 级 别 配 置 
调用 所 有 邮件 模块 的 


init_main_conf 方 法 


人 srv_conf 
级 别 的 配置 项 


构造 监听 端口 el | 
设置 新 连接 事件 的 回 


图 13-4 ”邮件 框 染 初 始 化 的 流程 图 


上 壕 过 程 实际 上 就 是 图 10-9 的 简化 版 ， 这 里 不 再 细 说 。 其 中 最 后 
一 步 中 设置 的 TCP 连 接 建 立成 功 后 的 回调 方法 为 
ngx_mail_ init_connection, 在 13.3 节 中 会 说 明 此 方法 。 


13.3 ”初始 化 请 : 


Nginx 与 客户 端 建立 TCP 连 接 后 ， 将 会 回调 ngx_mail_init connection 
方法 开始 初始 化 邮件 协议 ， 这 是 在 处 理 每 个 邮件 请 求 前 必须 要 做 的 工 
作 。 其 中 ， 初 始 化 请 求 时 将 会 创建 类 似 于 HITP 请 求 中 的 
ngx_http_request_t 这 样 的 核心 结构 体 : ngx_mail_session {， 在 13.3.1 
中 将 会 对 它 进行 介绍 。 另 外 ， 在 13.3.2 节 中 会 说 明 TCP 连 接 建 立成 功 时 
ngx_mail_init_connection 方 法 到 底 做 了 哪些 工作 。 


13.3.1 描述 邮件 请 求 的 ngx_mail_session_t 结 构 体 


ngx_mail_session_t 结 构 体 保存 了 一 个 邮件 请 求 的 生命 周期 里 所 有 
可 能 用 到 的 元 素 ， 如 下 所 示 。 


typedef struct { 
// 目前 未 使 


Uint32_t signature; 
// 下 游客 户 站 与 


Nginx 之 间 的 连接 


ngx_connection_t *connection; 


// out 中 可 以 存放 需要 向 下 游客 户 端 发 送 的 内 容 


ngx_str_t out 
/* 这 个 缓冲 区 用 于 接收 来 自 客户 端的 请 求 。 这 个 缓冲 区 中 所 使 用 的 内 存 大 小 与 请 求 是 有 关系 的 ， 对 于 


POP3 请 求 固定 为 


128 字 节 ， 对 于 


SMTP 请 求 ， 


nginx.conf 配 置 文件 中 的 


I 


smtp_client_buffer 配 置 项 决定 ， 对 了 


IMAP 请 求 ， 则 


imap_client_buffer 配 置 项 决定 


A 
ngx_buf_t *buffer; 
/*ctx 将 指向 一 个 指针 数组 ， 它 的 含义 与 
HTTP 请 求 的 


ngx_http_request_t 结 构 体 中 的 
Ctx 一致， 保存 着 这 个 请 求 中 各 个 邮件 模块 的 上 下 文 结构 体 指针 


wh 
void **ctx; 


// main 级 别 配 置 结构 体 组 成 的 指针 数组 


void **main_conf; 


/A*srv 级 别 配 置 结构 体 组 成 的 指针 数组 ， 这 两 个 指针 数组 的 意义 与 第 


10 章 介绍 过 的 
HTTP 框 架 中 的 同名 数组 基本 一 致 ， 只 是 它们 是 用 于 
main{} 配 置 块 下 的 配置 结构 体 


WA 


void **srv_conf; 


// 解析 主机 域名 


ngx_resolver_ctx_t *resolver_ctx; 
/* 请 求 经 过 认证 后 ， 


Nginx 就 开始 代理 客户 端 与 邮件 服务 器 间 的 通信 了 ， 这 时 会 生成 
proxy 上 下 文 用 于 此 目的 ， 详 见 


13 .5 节 


4 
ngx_mail_ proxy_ctx_t *proxy; 
/* 表 示 与 邮件 服务 器 交互 时 ， 当 前 处 理 哪 种 状态 。 对 于 


POP3 请 求 来 说 ， 会 隶属 了 


ngx_pop3_state_e 定 义 的 
7 种 状态 ， 对 于 


IMAP 请 求 来 说 ， 会 隶属 于 


ngx_imap_state_e 定 义 的 


8 种 状态 ， 对 于 


SMTP 请 求 来 说 ， 会 隶属 了 


ngx_smtp_state_e 定 义 的 


13 种 状态 


* 
ngx_uint_t mail_ state; 
// 邮件 协议 类 型 目前 仅 有 以 下 


3 个 


// #define NGX_MAIL_POP3_PROTOCOL 0 
// #define NGX_MAIL_ IMAP_ PROTOCOL 1 
// #define NGX_MAIL SMTP_PROTOCOL 2 


unsigned protocol:3; 
// 标志 位 。 


blocked 为 


1 时 表示 当前 的 读 或 写 操作 需要 被 阻塞 


unsigned blocked:1; 
// 标志 位 。 


unsigned quit:1; 
// 以 下 


3 个 标志 位 仅 在 解析 具体 的 邮件 协议 时 由 邮件 框架 使 


unsigned quoted:1; 

unsigned backslash:1; 
unsigned no_sync_literal:1; 
/* 当 使 


SSL 协 议 时 ， 该 标志 位 为 


1 说 明 使 用 


TLS 传 输 层 安全 协议 。 由 于 本 书 不 涉及 


SSL， 故 略 过 


*/ 
unsigned starttls:1; 


/* 表 示 与 认证 服务 器 交互 时 的 记录 认证 方式 。 


6 个 预 设 值 ， 分 别 是 : 


#define NGX_MAIL AUTH_PLAIN 
#define NGX_MAIL AUTH_LOGIN 


天 月 


#define 
#define 
#define 
#define 


unsigned auth_ method:3; 


/* 用 于 认 j 


1 时 表示 得 知 认 订 


E 服 务 器 的 标志 位 ， 为 
服务 器 要 求 暂缓 接收 响应 ， 这 时 


Nginx 会 继续 等 待 认证 服务 器 的 后 续 响 应 


*/ 


unsigned auth wait:1,; 


NGX_MAIL_AUTH_LOGIN_USERNAME 
NGX_MAIL_AUTH_APOP 
NGX_MAIL_AUTH_CRAM_MD5 
NGX_MAIL_AUTH_NONE 


/* 用 于 验证 的 用 户 名 ， 在 与 


Auth-User 头 部 


*/ 


ngx_str_t login; 


/* 相 对 于 


认证 服务 器 交互 后 会 被 设 为 认证 服务 


login 用 户 名 的 密码 ， 在 与 认证 有 


Auth-Pass 头 部 


*/ 


ngx_str_t passwd; 


// 作为 


Auth-Salt 验 证 的 信息 


ngx_str_t Salt 


A/ WF 


3 个 成 员 仅 用 于 


IMAP 通 信 


ngx_str_t tag; 
ngx_str_t tagged line,; 
ngx_str_t text; 


// 当前 


连接 上 对 应 的 


Nginx 服 务 器 地 址 


有 务 器 交互 


ngx_str_t *addr_text,; 
// 主机 地 址 


ngx_st 


// 以 下 


r_t host ， 


4 个 成 员 仅 用 于 


SMTP 的 通信 


unsigned esmtp:1; 


ngx_st 


r_t smtp_helo; 


后 


OO 上 wmN 


WA 


会 被 设 为 认证 


器 返回 的 响应 中 的 


的 响应 中 的 


ngx_str_t smtp_from; 
ngx_str_t smtp_to; 
/* 在 与 邮件 服务 器 交互 时 〈 即 与 认证 服务 器 交互 之 后 ， 透 传 上 下 游 


TCP 流 之 前 ) 


一 


件 服务 器 的 消息 类 型 


command 表 示人 解析 


*/ 
ngx_uint_t command; 
// args 动 态 数组 中 会 存放 来 自 下 游客 户 端的 邮件 协议 中 的 参数 


ngx_array_t args; 


// 当前 请 求 尝试 访问 认证 服务 器 验证 的 次 数 


ngx_uint_t login_attempt; 
// 以 下 成 员 用 于 解析 


POP3/IMAP/SMTP 等 协议 的 命令 行 


ngx_uint_t state,; 

u_char *cmd_start,; 

u_char *arg_start,; 

u_char *arg_end; 

ngx_uint_t literal len,; 
} ngx_mail_ session tt' 


想 要 了 解 邮件 框 染 的 处 理 流程 ， 离 不 开 ngx_mail_session_t 结 构 体 
的 帮助 。 如 果 在 阅读 邮件 请 求 的 处 理 过 程 中 过 到 ngx_mail_session t 结 
构 体 的 成 员 ， 那 么 可 以 返回 本 章 查 询 其 意义 。 


13.3.2 ”初始 化 邮件 请 求 的 流程 


初始 化 邮件 请 求 的 流程 非常 商 单 ， 如 岁 13-5 所 示 。 


为 请 求 创 建 
nsx_mail session_t 结构 体 


根据 TCP 连 接 上 本 机 疹 口 找到 对 应 的 


SC Tver 配 置 块 


设置 nex_mail_send 
为 回 客 户 闪 发 送 啊 应 的 方法 


根据 server 配 置 块 里 设置 的 协议 调用 相应 


邮件 : 模 所 的 init_se ssion 方 法 


图 13-5 ”初始 化 邮件 请 求 的 流程 


实际 上 ， 初 始 化 流程 中 最 关键 的 一 步 就 是 调用 POP3、SMTP、 
IMAP 等 具体 邮件 模块 实现 ngx_mail_protocol_t 接 口中 的 init_session 方 
法 ， 这 些 邮 件 模 块 会 根据 自己 处 理 的 协议 类 型 初始 化 
ngx_mail_session_t 结 构 体 。 在 POP3、SMTP、IMAP 邮 件 模 块 内 实现 的 
init_session 方 法 中 ， 都 会 设置 由 各 自 实 现 的 init_protocol 方 法 接收 、 解 


析 客 户 端 请 求 ， 这 里 不 再 详细 说 明 每 个 邮件 模块 是 如 何 实现 init_session 
方法 的 。 


13.4 ”接收 并 解析 客户 痪 请 求 


无 论 是 POP3、SMTP 还 是 IMAP 邮 件 模 块 ， 在 处 理 客户 端的 请 求 
时 ， 都 是 使 用 ngx_mail_protocol_t 接 口中 的 init_protocol 方 法 完成 的 ， 
它们 的 流程 十 分 相似 : 首先 反复 地 接收 客户 端 请 求 ， 并 使 用 状态 机 人 解 
析 是 否 收 到 足够 的 信息 ， 直 到 接收 了 完整 的 信息 后 才 会 跳 到 下 一 个 邮 
件 认证 阶段 执行 (通过 调用 ngx_mail_auth 方 法 ) 。 


使 用 状态 机 解析 来 目 客 户 端的 TCP 流 的 方法 其 实 就 是 通过 
ngx_mail_protocol_t 接 口中 的 parse_command 方 法 来 完成 的 ，POP3、 
SMTP、IMAP 邮 和 件 模块 实现 的 parse_command 方 法 都 在 
ngx_mail_parser.c 源 文件 中 。 由 于 本 章 不 涉及 邮件 协议 的 细节 ， 这 里 不 
再 一 一 说 明 。 


13.5 邮件 认 证 


邮件 认证 工作 由 ngx_mail_auth 方 法 执行 。 邮 件 认证 服务 器 的 地 址 
在 nginx.conf 文 件 的 auth_http 配 置 项 中 设置 (参见 13.1 节 ) ， 这 一 认证 
流程 相对 独立 ， 其 认证 功能 是 由 ngx_mail_auth_http_module 邮 件 模块 
提供 的 。 在 与 认证 邮件 服务 器 打交道 的 过 程 中 ， 结 构 体 
ngx_mail_auth_http_ctx_{t 会 贯穿 其 始终 ， 它 保存 有 连接 、 请 求 内 容 、 
啊 应 内 容 、 解 析 状 态 等 必要 的 成 员 ， 在 认证 完 邮 件 后 将 会 通过 销 嗓 内 
存 池 来 销毁 这 个 结构 体 。 


13.5.1 ngx_mail_auth_http_ctx_t 结 构 体 


ngx_mail_auth_http_ctx_t 结 构 体 是 在 其 成 员 pool 指 向 的 内 存 池 中 分 
配 的 ， 它 的 地 址 实际 上 保存 在 ngx_mail_session_t 的 ctx 指 针 数 组 中 ( 实 
际 上 ， 在 ngx_mail_auth_http_module 模 块 ctx_index 成 员 指出 的 序号 对 应 
的 ctx 数 组 元 素 中 ， 相 当 于 该 模块 的 上 下 文 结构 体 ) 。 邮 件 框架 提供 给 
各 个 邮件 模块 的 两 个 方法 用 于 在 ctx 指 针 数组 中 设置 、 取 出 上 下 文 结构 
体 的 地 址 ， 如 下 所 示 。 


#define ngx_mail get_ module_ctx(s, module) (Ss)->ctx[module.ctx_index] 
#define ngx_mail_set_ctx(s, c, module) s->ctx[module.ctx_index] = c; 


其 实际 用 法 跟 HTTP 框 架 中 的 ngx_http_set_ctx 方 法 非常 相似 。 例 
如 ， 假 设 指针 ctx 就 是 刚刚 分 配 的 ngx_mail_auth_http_ctx_t 结 构 体 地 
址 ， 而 s 是 每 个 请 求 的 ngx_mail_session_t 结 构 体 指针 ， 那 么 可 以 这 样 设 
置 到 请 求 的 ctx 数 组 中 : 


ngx_mail set_ctx(s, ctx, ngx_mail auth_http_module); 


下 面 详细 介绍 ngx_mail_auth_http_ctx_t 结 构 体 中 的 每 个 成 员 。 


typedef struct ngx_mail auth http ctx_s ngx mail auth_http_ctx_t; 
// 解析 认证 服务 器 


HTTP 响 应 的 方法 指针 


typedef void (*ngx_mail auth http_handler_pt) (ngx_mail_session t *S， 
ngx_mail auth_http_ctx_t *ctx); 
struct ngx_mail auth_http_ctx_s { 

/* request 缓 冲 区 保存 着 发 往 认 证 服务 器 的 请 求 。 它 是 根据 解析 客户 端 请 求 得 到 的 


ngx_mail session t， 使 用 


ngx_mail_auth_http_create_request 方 法 构造 出 的 内 存 缓冲 区 。 这 里 的 请 求 是 一 种 类 


HTTP 的 请 求 
ngx_buf t *request 


// 保存 认证 服务 器 返回 的 类 
HTTP 响 应 的 缓冲 区 。 缓 冲 区 指向 的 内 存 大 小 固定 为 


1KB 
ngx_buf_t *response; 


// Nginx 与 认证 服务 器 间 的 连接 


ngx_peer_connection_t peer; 


/* 解 析 来 自 认 证 服务 器 类 
HTTP 的 响应 行 、 头 部 的 方法 (参见 图 
13-6) ， 默 认为 


ngx_mail_auth_http_ignore_status_line 方 法 


2 


ngx_mail_auth_http_handler_pt handler; 
/* 在 使 用 状态 机 解析 认证 服务 器 返回 的 类 


HTTP 响 应 时 ， 使 


state 表 示 解 析 状 态 


ngx_uint_t state,; 
/* ngx_mail auth_http_parse_header_line 方 法 负责 解析 认证 服务 器 发 来 的 响应 中 类 


HTTP 的 头 部 ， 以 下 
4 个 成 员 用 于 解析 响应 头 部 


4 


u_char *header_name_start ， 
u_char *header_name_end ; 
u_char *header_start 
u_char *header_end,; 


// 认证 服务 器 返回 的 


Auth-Server 头 部 


ngx_str_t addr; 
// 认证 服务 器 返回 的 


Auth-Port 头 部 


ngx_str_t port; 
// 错误 信息 


ngx_str_t err; 
// 错误 信息 构成 的 字符 串 


ngx_str_t errmsg 


/* 错 误 码 构成 的 字符 串 。 如 果 认 证 服务 器 返回 的 头 部 里 


Auth-Error-Code， 那么 将 会 设置 到 


errcode 中 。 


errmsg 和 


errcode 在 发 生 错误 时 会 直接 将 其 作为 响应 发 给 客户 端 


*/ 


ngx_str_t errcode; 
/* 认 证 服务 器 返 区 


Auth-Wait 头 部 时 带 的 时 间 戳 将 会 被 设 到 


sleep 成 员 中 ， 而 


Nginx 等 待 的 时 间 也 将 


sleep 维 护 ， 当 


sleep 降 为 
9 时 将 会 设置 


quit 标 志 位 为 


肖 


1， 表 示 请 求 非 正常 结束 ， 把 错误 码 返 回 给 用 户 


time_t sleep 
// 


用 于 邮件 认证 的 独立 内 存 池 ， 它 的 初始 大 小 为 


2KB 
ngx_pool_t *pool 
/ 


13.5.2 与 认证 服务 器 建立 连接 


13-6 中 摘 述 了 ngx_mail_auth 方 法 所 做 的 工作 ， 包 括 初 始 化 与 认 
证 服务 器 交互 之 前 的 工作 、 发 起 TCP 连 接 等 


图 13-6 中 设置 了 Nginx 与 下 游客 户 端 间 TCP 连 接 上 的 读 事件 处 理 方 
法 为 ngx_mail_auth_http_block_read， 这 个 方法 所 做 的 唯一 工作 其 实 就 
是 再 次 调用 ngx_handle_read_event 方 法 把 读 事件 义 添加 到 epoll 中 ， 这 
意味 着 它 不 会 读 取 任何 客户 端 发 来 的 请 求 ， 但 同时 保持 着 读 事 件 被 
epoll 监控 。 在 与 认证 服务 器 间 TCP 连 接 上 ， 写 事件 的 处 理 方法 为 
ngx_mail_auth_http_write_handler， 它 负责 把 构造 出 的 request 绥 冲 区 中 
的 请 求 发 送 给 认证 服务 器 ， 读 事件 的 处 理 方法 为 
ngx_mail_auth_http_read_handler， 这 个 方法 在 接收 到 认证 服务 器 的 啊 
应 后 会 调用 ngx_mail_auth_http_ignore_status_line 方 法 首先 解析 HTTP 响 


应 行 。 


将 接收 客户 端 请 求 的 buffer 
缓冲 区 清空 


login_attempt 表 示 的 认证 
尝试 次 数 加 1 


分 配 2KB 的 内 存 池 用 于 访问 认证 服务 器 ， 
认证 时 使 用 的 内 存 都 由 该 内 存 池 中 分 配 


建立 ngx_mailauth_http_ctx_t 


在 绥 冲 区 request 
上 构造 发 往 认证 服务 器 的 请 求 


向 认证 服务 器 发 起 连接 ， 
同时 把 套 接 字 加 入 epol 和 定时 器 中 


设置 下 游 连接 上 的 读 
事件 处 理 方 法 


设置 与 认证 服务 器 间 连 接 的 


设置 与 认证 服务 器 间 连 接 的 
写 事件 处 理 方法 
[检查 TCP 连接 是 否 建立 成 功 ] 


[与 认证 服务 器 间 连 接 建 立成 功 ] 


调用 ngx mailauth http_write_ handler 


方法 向 认证 服务 器 发 送 请 求 


[TCP 连接 和 暂 未 建立 成 功 ] 


图 13-6 ”启动 邮件 认证 、 向 认证 服务 器 发 起 连接 的 流程 


13.5.3 ”发 送 请 求 到 认证 服务 大 


ngx_mail_auth_http_write_handler 会 发 送 request 绥 冲 区 中 的 请 求 到 
认证 服务 硕 ， 它 的 代码 非常 简单 ， 如 下 所 示 。 


static void ngx_mail auth_ http_write handler(ngx_event_t *wev) 


{ 


ssize_t n, size,; 
ngx_connection t *c; 

ngx_mail_ session _t *s,; 

ngx_mail _ auth_http_ctx_t *ctx; 
ngx_mail_auth_http_conf t *ahcf; 
// 写 事 件 上 的 


data 成 员 存放 的 是 


Nginx 与 认证 服务 器 间 的 


TCP 连 接 

C = wev->data; 

// 连接 的 
date 成 员 指 向 
ngx_mail_session_t 结 构 体 


S = c->data; 
// 获得 描述 认证 过 程 的 


ngx_mail_auth_http_ctx_t 结 构 体 


ctx = ngx_mail get module ctx(s, ngx_mail auth_http_module); 


/* 如 果 向 认证 服务 器 发 送 请 求 超时 ， 则 关闭 连接 、 销 毁 内 存 池 ， 并 向 客户 端 发 送 错 误 响 应 


*/ 
if (wev->timedout) 区 
ngx_close_connection(c); 
ngx_destroy_pool(ctx->pool); 
ngx_mail_session_internal_ server_error(s); 
return; 


} 
/计算 还 剩 下 多 少 字 节 的 请 求 没 有 发 送出 去 ， 


pos 和 


last 之 间 的 内 容 就 是 待 发 送 的 请 求 


*/ 


size = ctx->request->last - ctx->request->pos; 


// 向 认 订 


服务 器 发 送 请 求 


n = ngx_send(c, ctx->request->pos, size); 


// 如 果 发 送 失败 ， 则 关闭 连接 、 销 毁 内 存 池 ， 并 向 客户 端 发 送 错误 响应 


if (n == NGX_ERROR) { 
ngx_close_connection(c); 
ngx_destroy_pool(ctx->pool); 
ngx_mail session_internal_ server_error(s); 
return; 


} 
// 如 果 成 功 发 送 了 请 求 


if (n > 


0) { 


// 更 新 


request 缓 冲 区 


ctx->request->pos += ni 
/*size 表 示 还 需要 发 送 的 请 求 长 度 ， 


n 表 示 本 次 发 送 的 请 求 长 度 ， 当 它们 相等 时 ， 意 味 着 已 经 将 全 部 响应 发 送 到 认证 服务 器 


4 


if (n == Size) { 


Nginx 与 认证 服务 器 间 连 接 的 写 事 


/* 将 


件 回 调 方法 设 为 任何 事情 都 不 做 的 


= 


ngx_mail auth_http_dummy_handler 方 法 


除 


*/ 


epoll 中 


wev->handler = ngx_mail auth_http_dummy_handler; 


/* 由 于 不 再 需要 发 送 请 求 ， 所 以 不 需要 再 监控 发 送 是 否 超时 。 如 果 写 事件 还 在 定时 器 中 ， 


if (wev->timer_set) { 
ngx_del timer (wev); 


} 
// 将 写 事件 添加 到 


if (ngx_handle write event(wev, 0) != NGX_ OK) { 
ngx_close_connection(c); 
ngx_destroy_pool(ctx->pool); 
ngx_mail_session_internal server_error(s); 


} 


return; 


则 移 


} 
// 如 果 定 时 器 中 没有 写 事件 ， 那 么 把 它 添加 到 定时 器 中 监控 发 送 请 求 是 否 超时 


if (!wev->timer_set) { 
ahcf = ngx_mail get module srv_conf(s, ngx_ mail auth_http_module); 
ngx_add_ timer(wev, ahcf->timeout); 


13.5.4 接收 并 解析 响应 


接收 并 解析 认证 服务 器 啊 应 的 方法 是 
ngx_mail_auth_http_read_handler， 该 方法 要 同时 负责 解析 啊 应 行 和 
HTTP 头 部 ， 较 为 复杂 ， 图 13-7 描 述 了 其 中 的 主要 流程 。 


图 13-6 中 所 描述 的 流程 包括 两 个 阶段 ， 首 先 接收 到 完整 的 HTTP 啊 
应 行 ， 其 次 接收 到 完整 的 HTTP 响 应 头 部 。 这 两 个 阶段 都 并 非 一 次 调度 
就 一 定 可 以 完成 的 ， 因 此 ， 当 没有 收 到 足够 的 TCP 流 供 状态 机 解析 
时 ， 都 会 期 得 epoll 下 一 次 重新 调度 图 13-6 中 的 流程 。 在 全 部 解析 完 啊 
应 后 ， 将 可 以 得 知 认证 是 否 通过 ， 如 果 请 求 合 法 ， 那 么 可 以 从 HTTP 响 
应 头 部 中 得 到 上 游 邮 件 服务 圳 的 地 址 ， 接 着 通过 调用 
ngx_mail_proxy_init 方 法 进入 与 邮件 服务 器 交互 的 阶段 。 


13.6 ” 写 上 游 邮 件 服务 如 间 的 认证 交互 


对 于 POP3、SMTP、IMAP 来 说 ， 客 户 端 与 邮件 服务 器 之 间 最 初 的 
交互 目的 都 不 太 相 同 。 例 如 ， 对 于 POP3 和 IMAP 来 说 ， 与 邮件 服务 器 间 
的 TCP 连 接 一 旦 建立 成 功 ， 邮 件 服务 器 会 发 送 一 个 欢迎 信息 ， 接 着 客户 
端 (此 时 ，Nginx 是 邮件 服务 器 的 客户 端 ) 发 送 用 户 名 ， 在 邮件 服务 器 
返回 成 功 后 再 发 送 密码 ， 等 邮件 服务 器 验证 通过 后 ， 才 会 进入 到 邮件 
处 理 阶段 : 对 于 Nginx 这 个 邮件 代理 服务 器 来 说 ， 就 是 进入 到 纯粹 地 透 
传 Nginx 与 上 、 下 游 间 两 个 TCP 连 接 之 间 的 数据 流 ( 见 13.7 节 ) 。 但 对 
于 SMTP 来 说 ， 这 个 交互 过 程 又 有 所 不 同 ， 进 入 邮件 处 理 阶 段 前 需要 交 
互 传输 邮件 来 源 地 址 、 邮 件 目 标 地 址 (也 就 是 From...To...) 等 信息 。 


[检查 读 事件 上 的 timeout 标 志 位 是 否 超时 ] 


[接收 未 超时 , 再 检查 response 是 否 已 分 配 内 存 用 于 接收 响应 ] 


-esponse 组 冲 区 已 存在 
Leap 一 合生] [未 分 配 用 于 接收 响应 的 内 存 缓冲 区 ] 


在 response 绥 冲 区 上 分 配 1KB 
的 内 存 用 于 接收 认证 服务 器 响应 


[接收 响应 超时 ] 


使 用 recv 方 法 在 reponse 
上 接收 响应 


[ 检查 recv 方 法 的 返 


回 值 ] 


[接收 到 响应 ] [失败 或 者 连接 意外 关闭 ] 


调用 ngx_mail_auth_http_ignore_status_line 


已 经 解析 过 响应 行 ， 方法 解析 响应 行 
次 应 解析 HTTP 尖 中] [检查 是 否 接收 到 完整 的 响应 行 ] 


[解析 响应 行 出 错 ] 


[解析 到 完整 响应 行 , 开始 解析 HTTP 头 部 ] 


设置 ngxmail _auth_http_process_headers 
为 解析 HTTP 头 部 的 方法 


收 ] [检查 是 否 接收 到 完整 的 HTTP 头 部 ] 


[未 接收 到 完整 响应 行 
需要 等 竺 下 次 调度 继续 搂 


关闭 与 认证 服务 器 
调用 ngx_mail_auth_http_process_headers 间 的 连接 

析 头 部 
[检查 是 否 接收 到 完整 HTTP 头 部 ] 


[解析 头 部 出 错 ] 


销毁 用 于 认证 邮件 的 
内 存 池 


回 客 户 端 
发 送 错误 


[解析 到 完整 头 部 , 认证 成 功 ] 


[未 接收 完 头 部 ， 
等 待 下 一 次 调度 ] 


关闭 连接 ， 销 毁 内 存 池 ， 
进入 下 一 阶段 


图 13-7 ”接收 并 解析 来 目 认 证 服务 器 的 响应 


无 论 如 何 ，Nginx 作 为 邮件 代理 服务 万 在 接收 到 客户 端的 请 求 ， 并 
是 收集 到 足够 进行 认证 的 信息 后 ， 将 会 由 Nginx 与 上 游 的 邮件 服务 右 进 
行 独 立 的 交互 ， 直 到 邮件 服务 器 认为 可 以 进入 到 处 理 阶 段 时 ， 才 会 开 
始 透 传 协议 。 这 一 阶段 将 围绕 着 ngx_mail_proxy_ctx_t 结 构 体 中 的 成 员 
进行 。 下 面 以 POP3 协 议 为 例 简 单 地 说 明 Nginx 是 如 何 与 邮件 服务 器 交互 
i 


13.6.1 ngx_mail_proxy_ctx_t 结 构 体 


ngx_mail_session_t 结 构 体 中 的 proxy 成 员 指 同 ngx_mail_proxy_ctx_t 
结构 体 ， 该 结构 体 含有 Nginx 与 上 游 则 的 连接 upstream， 以 及 与 上 游 通 
信 时 接收 上 游 TCP 消 息 的 绥 冲 区 ， 如 下 所 示 。 


typedef struct { 
// 与 上 游 邮件 服务 器 间 的 连接 


ngx_peer_connection_t upstream; 
/* 用 于 缓存 上 、 下 游 间 


TCP 消 息 的 内 存 缓冲 区 ， 内 存 大 小 由 


nginx.conf 文 件 中 的 


proxy_buffer 配 置 项 决定 


*/ 
ngx_buf_t *buffer,; 
} ngx_mail proxy_ctx_t; 


了 @ 注意 。proxy 成 员 最 初 也 是 NULL 空 指针 ， 直 到 调用 
ngx_mail_proxy_init 方 法 后 才 会 为 proxy 指 针 分 配 内 存 。 


13.6.2” 回 上 游 邮 件 服 务 需 发 起 连接 


根据 ngx_mail_proxy_init 方 法 可 以 局 动 Nginx 与 上 游 邮 件 服务 右 间 
的 交互 ， 下 面 看 一 下 该 方法 主要 做 了 哪些 工作 。 


void ngx_mail_proxy_init(ngx_mail_session t *s, ngx_addr_t *peer) 


{ 


// 创建 


ngx_mail_proxy_ctx_t 结 构 体 


ngx_mail proxy_ctx_t *p = ngx_pcalloc( s->connection->pool, 
sizeof (ngx_mail proxy_ctx_t)); 
if (p == NULL) { 
ngx_mail_ session_internal_ server_error(s); 
return; 


} 
// 注意 ， 之 前 的 


proxy 成 员 指向 的 是 


NULL 空 指针 


s->proxy = p; 


// 向 上 游 的 邮件 服务 器 发 起 无 阻塞 的 


TCP 连 接 


ngx_int_t rc = ngx_event_connect_peer(&p->upstream); 


/* 需 要 监控 接收 邮件 服务 器 的 响应 是 否 超 时 ， 于 是 把 与 上 游 间 连接 的 读 事件 添加 到 定时 器 中 


*/ 
ngx_add_timer(p->upstream.connection->read, cscf->timeout); 
// 设置 连接 的 

data 成 员 指向 


ngx_mail_session_t 结 构 体 


p->upstream.connection->data = s,; 


/* 设 置 


Nginx 与 客户 端 间 连 接 读 事 件 的 回调 方法 为 不 会 读 取 内 容 的 


ngx_mail_proxy_block_read 方 法 ， 因 为 当前 阶段 
Nginx 不 会 与 客户 端 交互 
“7 


s->connection->read->handler = ngx_mail proxy_block_read; 
/* 设 置 


Nginx 与 上 游 间 的 连接 写 事件 回调 方法 为 什么 事 都 不 做 的 


ngx_mail_proxy_dummy_handler 方 法 ， 这 意味 着 接 下 来 向 上 游 发 送 


TCP 流 时 ， 将 不 再 通过 


epo1ll 这 个 事件 框架 来 调度 ， 下 一 节 将 看 到 实际 的 用 法 


*/ 
p->upstream.connection->write->handler = ngx_mail proxy_dummy_handler; 
/* 建 立 


Nginx 与 邮件 服务 器 间 的 内 存 缓 促 区 ， 绥 冲 区 大 小 由 


nginx.conf 文 件 中 的 


[=3 


proxy_buffer 配 置 项 决定 


*/ 
S->proxy->buffer = ngx_create_ temp_buf(s->connection->pool, 
pcf->buffer_size); 


// 注意 ， 设 


out 为 空 ， 表 示 将 不 会 再 通过 


out 向 客户 端 发 送 响 应 


亚 
| 


Ss->out.len = 


90; 
// 根据 用 户 请 求 的 协议 设置 实际 的 邮件 认证 方法 


Switch (s->protocol) { 
case NGX_MAIL_ POP3_PROTOCOL: 
// 设置 


POP3 协 议 进行 邮件 交互 认证 的 方法 


p->upstream.connection->read->handler = ngx_mail proxy_pop3_handler; 
s->mail_state = ngx_pop3_start,; 
break; 
case NGX_MAIL_IMAP_PROTOCOL : 
// 设置 


IMAP 进 行 邮件 交互 认证 的 方法 


p->upstream.connection->read->handler = ngx_mail proxy_imap_handler; 
s->mail_state = ngx_imap_start,; 


break; 
default: /* NGX_MAIL_SMTP_PROTOCOL */ 
// 设置 


SMTP 进 行 邮件 交互 认证 的 方法 


p->upstream.connection->read->handler = ngx_mail proxy_smtp_handler; 
s->mail_state = ngx_smtp_start,; 
break; 


} 
} 


可 以 看 到 ， 其 中 最 重要 的 工作 在 于 分 配 了 ngx_mail_proxy_ctx_t 结 
构 体 ， 并 为 成 员 buffer 分 配 了 内 存 缓冲 区 ， 用 于 接收 上 游 的 TCP 消 忆 ， 
同时 使 用 upstream 与 上 游 建 立 了 了 TCP 连接， 最 后 针对 不 同 的 邮件 协议 分 
别 设置 了 ngx_mail_proxy_pop3_handler、ngx_mail_proxy_imap_handler 
或 者 ngx_mail_proxy_smtp_handler 方 法 ， 用 于 Nginx 与 上 游 邮 件 服务 器 
间 的 交互 。 


13.6.3 与 邮件 服务 器 认证 交互 的 过 程 


由 于 每 种 协议 的 交互 过 程 都 不 相同 ， 因 此 下 面 仅 以 POP3 协 议 为 例 
简单 地 说 明 这 一 过 程 是 如 何 实现 的 ， 如 下 所 示 。 


static voidngx_mail_proxy_pop3_handler(ngx_event_t *rev) 


u_char *p; 

ngx_int_t rc; 
ngx_connection_t “Ci 
ngx_mail session t *s,; 
ngx_mail proxy_conf_t *pcf; 


// line 将 会 保存 发 往 上 游 邮 件 服务 器 的 消息 


ngx_str_t line,; 


// 获取 
Nginx 与 上 游 间 的 连接 


c = rev->data,; 
// 获得 


ngx_mail_session_t 结 构 体 


s = c->data; 


// 如 果 读 取 上 游 邮 件 服务 器 响应 超时 ， 则 向 客户 端 发 送 错 误 响 应 


if (rev->timedout) { 
c->timedout = 1; 


ngx_mail_ proxy_internal_ server_error(s); 


return; 


} 
// 读 取 上 游 邮 件 服务 器 发 来 的 响应 到 


buffer 绥 冲 区 中 


人 


rc 
// 


if (rc == NGX_AGAIN) { 
return; 
} 


// 消息 不 合法 ， 或 者 邮件 服务 器 没 


if (rc == NGX_ERROR) { 


ngx_mail_proxy_read_response(s, 0); 


验证 通过 ， 则 返 


:需要 继续 接收 邮件 服务 器 的 消息 ， 期 待 下 一 次 的 调度 


Ee 
了 TE 
wt 
< 
ny 
只 

Is 
alt 


区 
好 


ngx_mail_ proxy_upstream error(s); 


return; 


} 
switch (s->mail state) { 
case ngx_pop3_start: 


// 构造 发 送 给 邮件 服务 器 的 


户 信 


line.len = sizeof("USER ") - 1 + S->login.len + 2; 

line.data = ngx_pnalloc(c->pool, line.len); 

If (line.data == NULL) { 
ngx_mail proxy_internal_ server_error(s); 


return; 


"USER ", sizeof("USER ") - 1); 


= ngx_cpymem(p, s->login.data, s->login.1len); 


} 
p = ngx_cpymem(line.data, 
p = 


pt+ = CR; *p = LF; 


s->mail_state = ngx_pop3_user; 


break; 
case ngx_pop3_user: 


// 构造 发 送 给 邮件 服务 器 的 密码 信息 


line.len = sizeof("PASS ") 
line.data = ngx_pnalloc(c->pool, line.len); 
If (line.data == NULL) { 

ngx_mail proxy_internal_ server_error(s); 


return; 


- 1 + Ss->passwd.len + 2; 


p = ngx_cpymem(line.data, 
p = ngx_cpymem(p, 


p++ = CR; *p = LF; 
s->mail_state = ngx_pop3_passwd; 


break; 


case ngx_pop3_passwd: 
/* 在 收 到 服务 器 返回 的 密码 验证 通过 信息 后 ， 将 


Nginx 与 下 游客 户 端 间 、 


Nginx 与 上 游 


TCP 连 接 上 读 


"PASS ", 
s->passwd.data, 


后 服务 器 间 的 


/ 写 事 件 的 回调 方法 都 设置 为 


ngx_mail_proxy_handler 方 法 (参见 


sizeof("PASS ") - 1); 
s->passwd.1len); 


ngx_mail_proxy_handler; 


= ngx_mail proxy_handler; 


13.7 节 ) 
s->connection->read->handler 
s->connection->write->handler 
rev->handler = ngx_mail proxy_handler,; 
c->write->handler = ngx_mail proxy_handler; 
// 进入 透 传 上 、 下 游 

TCP 阶 段 
ngx_mail_proxy_handler(s->connection->write); 
return; 

default: 


#if (NGX_SUPPRESS_WARN) 
ngx_str_null(&line); 


#endif 
break; 


} 
/* 向 上 游 的 邮件 服务 器 发 送 验 证 


se 


是/ 局 。 术 


TCP 流 与 本 书 的 其 他 章节 都 不 相同 ， 它 不 再 i 


epol11 检 测 到 


TCP 连 接 上 出 现 可 写 事件 而 角 


通过 


由 发 。 事 实 上 ， 它 是 由 连接 上 


， 这 里 癌 邮 和 伯 


息 ， 才 向 邮件 服务 器 发 送 消 , 


TCP 消 息 包 都 非常 短小 


*/ 


tH 现 的 


服务 器 发 送 


读 事件 触发 的 ， 因 为 读 取 到 了 


息 。 之 所 以 可 以 这 么 做 


和 二 个 原 


寻 在 ] 


上 ， 当 前 阶段 发 送 的 


if (c->send(c, line.data, line.len) < (ssize t) line.len) { 


ngx_mail_ proxy_internal_ server_error(s); 


return; 
// 清空 


buffer 绥 冲 区 


从 


服务 器 的 消 


S->proxy->buffer->pos = s->proxy->buffer->start; 
s->proxy->buffer->last = S->proxy->buffer->Start， 


} 


一 旦 收 到 用 户 名 、 和 密码 验证 通过 的 消息 ， 束 会 由 
ngx_mail_proxy_handler 方 法 进入 透 传 上 、 下 游 TCP 流 的 阶段 。 


13.7 透 传 上 洲 邮 件 服务 右 与 客户 病因 的 流 


ngx_mail_proxy_handler 方 法 同时 负责 处 理 上 、 下 游 间 的 四 个 事件 
(两 个 读 事件 、 两 个 写 事件 ) 。 该 方法 将 完全 实现 上 、 下 游 邮 件 协 议 
之 间 的 透 传 ， 本 节 将 通过 直接 研究 这 个 方法 来 看 看 如 何 用 固定 大 小 的 
缓存 实现 透 传 功能 (有 些 类 似 于 upstream 机 制 转发 响应 时 仅 用 了 固定 
缓存 的 模式 ， 但 upstream 机 制 只 是 单 向 的 转发 ， 而 透 传 则 是 双向 的 转 
发 ) 。 


下 面 完 来 介绍 双向 转发 TCP 流 时 将 会 用 到 的 两 个 缓冲 区 : 
ngx_mail_session_t 中 的 buffer 缓 冲 区 用 于 转发 下 游客 户 剖 的 消 居 给 上 游 
的 邮件 服务 器 ， 而 ngx_mail_proxy_ctx_t 中 的 buffer 缓 冲 区 则 用 于 转发 上 
游 邮件 服务 器 的 消 恩 给 下 游 的 客户 端 。 在 这 两 个 hgx_buf_t 类 型 的 组 促 
区 中 ，pos 指 针 指 同行 转发 消 轧 的 起 始 地 址 ， 而 last 指 针 指 回 最 后 一 次 
接收 到 的 消息 的 末尾 。 当 pos 等 于 last 时 ， 意 味 着 全 部 缓存 消息 都 转发 
完了 ， 这 时 会 把 pos 和 last 都 指向 缓冲 区 的 首部 start 指 针 ， 相 当 于 清空 绥 
冲 区 以 便 再 次 复 用 完整 的 缓冲 区 。 相 关 代 码 如 下 所 示 。 


static void ngx_mail proxy_handler(ngx_event _t *ev) 


// 当前 的 动作 ， 用 于 记录 日 志 


char *action, *recv_action, *send_ action; 
/*size 变 量具 有 两 种 含义 : 在 读 取 消息 时 ， 


size 表 示 


recv 方 法 中 空 闪 缓冲 区 的 大 小 ， 在 发 送 消息 时 ， 表 示 将 要 发 送 的 消息 长 度 


Wh 
size_t size; 
// send 或 者 


recv 方 法 的 返回 值 


ssize_t n; 


// b 表 示 用 于 接收 
TCP 消 息 的 缓冲 区 ， 或 者 指向 用 于 发 送 消息 的 缓冲 


[Xl 


ngx_buf_t *b， 
// do_write 标 志 位 决定 本 次 到 底 是 发 送 还 是 接收 


TCP 消 息 


ngx_uint_t do write; 
/* 每 次 透 传 


TCP， 上 、 下 游 的 客户 端 与 邮件 服务 器 之 间 必 然 有 一 个 负责 提供 消 


BB, 


Nginx 转 发 的 消息 。 


src 用 来 表示 


Nginx 与 提供 消息 一 方 之 间 的 连接 ， 而 


dst 表 示 
Nginx 与 接收 消息 一 方 之 间 的 连接 


*/ 
ngx_connection t *c, *src, *dst; 
ngx_mail session t *s,; 
ngx_mail proxy_conf_t *pcf， 
/* 注 意 ， 事 件 


ev 既 可 能 属于 
Nginx 与 下 游 间 的 连接 ， 也 有 可 能 属 了 


Nginx 与 上 游 间 的 连接 ， 此 时 无 法 判断 连接 


c 究 况 是 来 自 于 上 游 还 是 下 游 


*/ 
c = ev->data; 


/* 无 论 是 在 上 游 连接 还 是 下 游 连接 上 ， 


ngx_connection_t 结 构 体 的 
data 成 员 都 将 指向 


ngx_mail_session_t 结 构 体 


ET 


， 男 一 个 负责 接收 


S 三 
// 


if 


TCP 连 接 


/ 


ngx_mai 


connect 


c->data; 


无 论 上 、 下 游 ， 只 要 接收 或 者 发 送 消 息 出 现 了 超时 ， 都 需要 终止 透 传 操作 


(ev->timedout) { 


// ngx_mail_proxy_close_session 方 法 会 同时 关闭 上 、 下 游 的 


ngx_mail proxy_close_session(s); 
return， 


1_ session _t 结 构 体 中 的 


ion 成 员 一 定 指向 


Nginx 与 下 游客 户 端 间 的 


TCP 连 接 


“/ 
if 


(Cc == s->connection) { 
// 以 下 分 文章 味 着 收 到 了 下 游 连接 上 的 事件 (无 论 是 可 读 事件 还 是 可 写 事 


if (ev->write) { 


/* 当 下 游 可 写 事件 被 触发 时 ， 意 味 着 本 次 


Nginx 将 负责 把 接收 自 上 游 的 缓存 消息 发 送 给 下 游 


9 


recv_action 
send_action 
// 设 


"proxying and reading from upstream"; 
"proxying and sending to client"; 


src 来 源 连接 为 上 游 连接 


src = s->proxy->upstream.connection; 
// 设 


dst 目 标 连接 为 下 游 连 接 


Nginx 将 负责 先 读 取 下 游 的 响应 到 缓存 中 ， 为 下 一 步 转发 给 上 游 做 准备 


dst = c; 
// 设 于 向 下 游 发 送 的 消息 缓冲 区 


b = S->proxy->buffer ; 


/* 当 下 游 可 读 事件 被 触发 时 ， 意 味 着 本 次 


4 
"proxying and reading from client"; 


recv_action 
"proxying and sending to upstream"; 


send_action 
// 设 


ll 


src 来 源 连接 为 下 游 连接 


src = Cc; 
// 设 


dst 目 标 连接 为 上 游 连接 


dst = s->proxy->upstream.connection; 
// 设置 用 于 接收 下 游 消息 的 缓冲 区 


b = s->buffer; 


} else { 
// 以 下 分 支 意味 着 收 到 了 上 游 连接 上 的 事 


件 


es 


if (ev->write) 区 


/* 当 上 游 可 写 事件 被 触发 时 ， 意 味 着 本 次 


Nginx 将 负责 把 接收 自 下 游 的 缓存 消息 发 送 给 上 游 


recv_action = "proxying and reading from client"; 
send_action = "proxying and sending to upstream",; 


// 设 


src 来 源 连接 为 下 游 连接 


src = s->connection; 
// 设 


dst 来 源 连接 为 上 游 连接 


dst = c; 


// 设 于 向 上 游 发 送 的 消息 缓冲 区 


b = s->buffer; 
} else { 
/* 当 上 游 可 读 事件 被 触发 时 ， 意 味 着 本 次 


Nginx 将 负责 接收 上 游 的 消息 到 缓存 中 ， 为 下 一 步 把 这 个 消息 转发 给 下 游 做 准备 


A 
"proxying and reading from upstream",; 


recv_action 
"proxying and sending to client"; 


send_action 
// 设 


src 来 源 连接 为 上 游 连接 


src = Cc; 
// 设 


dst 来 源 连 接 为 下 游 连 接 


dst = s->connection,; 
// 设置 用 于 接收 上 游 消息 的 缓冲 


Xl 


b = s->proxy->buffer,; 


// 当前 触发 事件 的 


write 标志 位 将 决定 


do_write 本 次 是 发 送 消 ) 


ET 


还 是 接收 消息 


do write = ev->write 1 : 0; 
/* 进 入 回 


dst 连 接 发 送 消息 或 者 由 
src 连 接 上 接收 消息 的 循环 ， 直 到 套 接 字 上 和 暂 无 可 读 或 可 写 事件 时 才 退 


A 
for ( ;; ) { 
if (do write) { 
// 如 果 本 次 将 发 送 


TCP 消 息 ， 那 么 首先 计算 出 要 发 送 的 消息 长 度 


= b 
// 检查 需要 发 送 的 消息 长 度 


size 是 否 大 于 


©， 以 及 目标 连接 当前 是 否 可 写 


if (size && dst->write->ready) { 
c->1l0g->action = send_ action; 
// 调 | 


send 方 法 向 
dst 目 标 连 接 上 发 送 


TCP 消 息 


n = dst->send(dst, b->pos, size); 
if (n == NGX_ERROR) { 
// 发 送 错误 时 直接 结束 请 求 


ngx_mail proxy_close_session(s); 
return; 


} 
if (n > 0) { 
// 更 新 消息 缓冲 区 


b->pos += n;// 如 果 缓 冲 区 中 的 消息 全 


if (b->pos == b->last) { 
b->pos = b->start,; 
b->last = b->start,; 


} 
} | 
// 为 下 面 读 取 


TCP 消 息 做 准备 ， 先 计算 接收 缓冲 区 上 的 空间 空间 大 小 


size = b->end - b->last,; 
// 检查 空间 缓冲 区 大 小 是 否 大 于 


9， 以 及 源 连接 上 当前 是 否 可 读 


if (size && src->read->ready) { 
C->1og->action = recv_action; 


// 调用 


recv 方 法 
src 源 连接 上 接收 


TCP 消 息 


n = src->recv(src, b->last, size); 
// 如 果 没 有 读 取 到 内 容 ， 或 者 对 方 主动 关闭 了 


TCP 连 接 ， 则 跳出 循环 


if (n == NGX_AGAIN || n == 0) { 
break; 


} 
if (n > 0) { 
// 如 果 读 取 到 了 消息 ， 则 应 试图 在 本 次 


ngx_mail_proxy_handler 方 法 的 执行 中 将 它 立 即 发 送出 去 


4 
do_write = 1; 
// 更 新 消息 缓冲 区 


b->last += n; 


// 重新 执行 循环 ， 检 查 是 否 可 以 立即 转发 


上 由 


continue; 


去 


部 发 送 完 ， 


则 清空 缓冲 区 以 复 


bmn 


if (n == NGX_ERROR) { 
src->read->eof = 1; 


} 
} 
break; 
} 
C->1og->action = "proxying"; 


// 如 果 上 、 下 游 间 的 连接 中 断 ， 则 结束 透 传 流程 


if ((s->connection->read->eof && S->buffer->pos == s->buffer->last) || (s- 
>proxy->upstream.connection->read->eof && s->proxy->buffer->pos == S->proxy- 
>buffer-> last) || (s->connection->read->eof && s->proxy->upstream.connection- 
>read->eof)) 

{ 

action = c->l0g->action; 
C->1og->action = NULL; 
C->1og->action = action,; 
ngx_mail_proxy_close_session(s); 
return; 


} 
// 下 面 将 会 


Nginx 与 上 、 下 游 


[ 旦 


TCP 连 接 上 的 


4 个 读 


/ 写 事 件 再 次 添加 到 


epoll 中 监控 


If (ngx_handle write event(dst->write, 0) != NGX_ OK) { 
ngx_mail_proxy_close_session(s); 
return; 


If (ngx_handle_read event(dst->read, 0) != NGX _ OK) { 
ngx_mail_proxy_close_session(s); 
return; 


If (ngx_handle write event(src->write, ©0) != NGX_ OK) { 
ngx_mail_proxy_close_session(s); 
return; 


If (ngx_handle_read event(src->read, 0) != NGX_ OK) { 
ngx_mail_proxy_close_session(s); 
return; 


} 
/* 接 收 下 游客 户 端的 消息 时 还 是 需要 检查 超时 的 ， 防 止 “ 僵 死 * 的 客户 端 占用 
Nginx 服 务 器 资源 


4h 
If (c == s->connection) { 
pcf = ngx_mail get module srv_conf(s, ngx_mail proxy_module); 
ngx_add_ timer(c->read, pcf->timeout); 


可 以 看 到 ，ngx_mail_proxy_handler 方 法 很 简单 ， 不 过 百 行 代码 就 
完成 了 透 传 功能 。 至 于 在 这 一 阶段 中 客户 端 完 竟 与 邮件 服务 器 交换 了 
哪些 消息 ， 作 为 邮件 代理 服务 器 Nginx 并 不 关心 。 这 个 阶段 将 会 一 直 持 
续 下 去 ， 直 到 客户 端 或 者 邮件 服务 器 有 一 方 关闭 了 TCP 连 接 ， 或 者 发 
送 、 接 收 TCP 消 息 达 到 了 超时 时 间 的 限制 为 止 。 


1 州 呈 阁 


本 草 介 绍 了 Nginx 是 如 何 设计 并 实现 官方 提供 的 邮件 代理 服务 大 
的 ， 当 需要 支持 新 的 邮件 协议 时 ， 类 似 于 HTTP 框 染 的 邮件 框架 可 以 较 
容易 地 集成 新 的 邮件 模块 。 邮 件 框架 和 HTTP 框 加 都 是 应 用 事件 框架 很 
好 的 例子 。 如 采用 户 更 希望 Nginx 作 为 基于 TCP 的 其 他 应 用 层 协 议 服务 
絮 ， 而 不 是 局 限于 Web 服 务 右 ， 那 么 可 以 对 比 和 参考 这 两 个 框 染 ， 编 
写 一 种 新 的 Nginx 模 块 ， 从 而 充分 利用 Nginx 底 层 的 强大 设计 功能 。 


第 14 革 ”进程 间 的 通信 机 制 


本 革 并 不 是 说 明 Linux 下 有 了 哪些 进程 通信 方式 ， 而 十 为 了 说 明 
Nginx 选 择 了 哪些 方式 来 同步 master 进 程 和 多 个 worker 进 程 间 的 数据 ， 
Nginx 框 架 古 怎样 重新 封 疾 了 这 些 进 程 间 通信 方式 的 ， 以 及 在 开发 
Nginx 模 块 时 应 该 怎样 使 用 这 些 封 痛 过 的 方法 。 


Nginx 由 一 个 master 进 程 和 多 个 worker 进 程 组 成 ， 但 master 进 程 或 
者 worker 进 程 中 并 不 会 再 创建 线程 (Nginx 的 多 线程 机 制 一 直 停 留 在 测 
斌 状态， 虽然 不 排除 未 来 Nginx 可 能 发 布 文 持 多 线程 版 本 的 可 能 性 ， 但 
直到 目前 最 新 的 1.2.x 版 本 仍然 未 支持 多 线程 ) ， 因 此 ， 本 章 的 内 容 不 
会 涉及 线程 间 的 通信 。 


14.1 概述 


Linux 提 供 了 多 种 进程 间 传 递 消 妃 的 方式 ， 如 共 译 内 存 、 万 接 字 、 
管道 、 消 轧 队 列 、 信 和 号 等 ， 每 种 方式 都 有 其 优 缺 点 ， 而 Nginx 框 以 使 用 
了 3 种 传递 消 轧 传递 方式 : 共 吾 内 存 、 套 接 字 、 信 和 号。 在 14.2 节 将 会 介 
绍 Nginx 是 怎样 使 用 、 封 装 共 至 内 存 的 ;在 14.4 让 会 介绍 进程 间 怎 样 使 
用 套 接 字 通 信 ， 以 及 如 何 使 用 基于 套 接 字 封闭 的 Nginx 频 道 ， 在 14.5 下 
中 将 会 介绍 进程 间 怎 样 通过 发 送 、 接 收 信和 号 来 传递 请 妃 。 


在 多 个 进程 访问 共 至 资源 时 ， 还 需要 提供 一 种 机 制 使 各 个 进程 有 
序 、 安 全 地 访问 资源 ， 避 人 免 并 发 访问 市 来 的 未 知 结果 。Nginx 主 要 使 用 
了 3 种 同步 方式 : 原子 控 作 、 信 和 号 量 、 文 件 锁 。 在 14.3 市 将 会 介绍 在 
Nginx 中 原子 操作 是 怎样 实现 的 ， 同 时 还 会 介绍 基于 原子 变量 实现 的 自 
旋 锁 ;在 14.6 世 将 会 介绍 信号 量 ， 与 “信号 ”不同 的 是 ， 中 文 译 名 仅 有 
一 字 之 差 的 “信号 量 ” 其 实 是 用 于 同步 代码 段 的 执行 的 ， 在 14.7 市 将 会 
介绍 文件 锁 。 


由 于 Nginx 的 每 个 worker 进 程 都 会 同时 处 理 千 万 个 请 求 ， 所 以 处 理 
任何 一 个 请 求 时 都 不 应 该 阻塞 当前 进程 处 理 后 续 的 其 他 请 求 。 例 如 ， 
不 要 随意 地 使 用 信号 量 互 不 锁 ， 这 会 使 得 worker 进 程 在 得 不 到 锁 时 进 
入 睡眠 状态 ， 从 而 导致 这 个 worker 进 程 上 的 其 他 请 求 被 <“ 饿 死 ”。 鉴 于 


此 ，Nginx 使 用 原子 操作 、 信 与 量 和 文件 锁 实现 了 一 套 ngx_shmtx_t 互 
不 锁 ， 当 操作 系统 支持 原子 操作 时 ngx_shmtx_t 束 由 原子 变量 实现 ， 否 
则 将 由 文件 锁 来 实现 。 顾 名 思 义 ，ngx_shmtx_t 锁 是 可 以 在 共享 内 存 上 
使 用 的 ， 它 是 Nginx 中 最 常见 的 锁 。 


14.2 ”共享 内 存 


共享 内 存 是 Linux 下 提供 的 最 基本 的 进程 间 通 信 方 法 ， 它 通过 
mmap 或 者 shmget 系 统 调用 在 内 存 中 创建 了 一 块 连续 的 线性 地 址 空间 ， 
而 通过 munmap 或 者 shmdt 系 统 调用 可 以 释放 这 块 内 存 。 使 用 共享 内 存 
的 好 处 钙 当 多 个 进程 使 用 同一 块 共 至 内 存 时 ， 在 任何 一 个 进程 修改 了 
共 至 内 存 中 的 内 容 后 ， 其 他 进程 通过 访问 这 上段 共 至 内 存 都 能 够 得 到 修 
改 后 的 内 容 。 


@ i 音 虽然 mmap 可 以 以 磁盘 文件 的 方式 映射 共 吾 内 存 ， 但 在 
Nginx 封 闭 的 共 亨 内 存 操作 方法 中 是 没有 使 用 到 映射 文件 功能 的 。 


Nginx 定 义 了 ngx_shm _t 结 构 体 ， 用 于 描述 一 块 共享 内 存 ， 代 码 如 
下 所 未 各 


typedef struct { 
// 指向 共享 内 存 的 起 始 地 址 


u_char *addr,; 
// 共享 内 存 的 长 度 


size_t size; 
// 这 块 共 享 内 存 的 名 称 


ngx_str_t name; 
// 记录 日 志 的 


ngx_log_t 对 象 


ngx_log_t *1og ， 


// 表示 共享 内 存 是 否 已 经 分 配 过 的 标志 位 ， 为 


1 时 表示 已 经 存在 


ngx_uint_t exists,; 
} ngx_shm_t; 


操作 ngx_shm_t 结 构 体 的 方法 有 以 下 两 个 : ngx_shm_alloc 用 于 分 
配 新 的 共享 内 存 ， 而 ngx_shm_free 用 于 释放 已 经 存在 的 共享 内 存 。 在 
描述 这 两 个 方法 前 ， 先 以 mmap 为 例 说 明 Linux 是 怎样 向 应 用 程序 提供 
共享 内 存 的 ， 如 下 所 示 。 


void *mmap(void *start, size t length, int prot, int flags, 
int fd, off_t offset); 


mmap 可 以 将 磁盘 文件 映射 到 内 存 中 ， 直 接 操作 内 存 时 Linux 内 核 

将 负责 同步 内 存 和 磁盘 文件 中 的 数据 ，fd 参 数 就 指向 需要 同步 的 磁 副 
文件 ， 而 offset 则 代表 从 文件 的 这 个 偏 移 量 处 开始 共享 ， 当 然 Nginx 没 
有 使 用 这 一 特性 。 当 flags 参 数 中 加 入 MAP_ANON 或 者 
MAP_ANONYMOUS 参 数 时 表示 不 使 用 文件 映射 方式 ， 这 时 fd 和 offset 
参数 束 没 有 意义 ， 也 不 需要 传递 了 ， 此 时 的 mmap 方 法 和 
ngx_shm_alloc 的 功能 几乎 完全 相同 。length 参 数 就 是 将 要 在 内 存 中 开 
辟 的 线性 地 址 空间 大 小 ， 而 prot 参 数 则 是 操作 这 段 共享 内 存 的 方式 

(如 只 读 或 者 可 读 可 写 ) ，start 参 数 说 明 希 望 的 共享 内 存 起 始 映 射 地 
址 ， 当 然 ， 通 常 都 会 把 start 设 为 NULL 空 指针 。 


先 来 看 看 如 何 使 用 mmap 实 现 ngx_shm_alloc 方 法 ， 代 码 如 下 。 


ngx_int_t ngx_shm_alloc(ngx_shm_t *shm) 


// 开辟 一 块 


shm->size 大 小 且 可 以 读 


/ 写 的 共享 内 存 ， 内 存 首 地 址 存放 


addr 中 


shm->addr = (u_char *) mmap(NULL, shm->size, 
PROT_READ | PROT_WRITE, 
MAP_ANON | MAP_SHARED, -1, 0); 
if (shm->addr == MAP_FAILED) { 
return NGX_ERROR ， 


} 
return NGX_OK; 


这 里 不 再 介绍 shmget 方 法 申请 共 至 内 存 的 方式 ， 它 与 上 述 代 码 相 
人 0 


当 不 再 使 用 共享 内 存 时 ， 需 要 调用 munmap 或 者 shmdt 来 释放 共 襄 
内 存 ， 这 里 还 是 以 与 mmap 配 对 的 munmap 为 例 来 说 明 。 


int munmap(void *start, size_t length ) ， 


其 中 ，start 参 数 指向 共享 内 存 的 首 地 址 ， 而 length 参 数 表 示 这 上 段 共 
享 内 存 的 长 度 。 下 面 看 看 ngx_shm_free 方 法 是 怎样 通过 munmap 来 释放 
共享 内 存 的 。 


void ngx_shm_free(ngx_shm_t *shm) 


{ 


// 使 


ngx_shm_t 中 的 


addr 和 


Size 人 参数 调 


munmap 释 放 共 享 内 存 即 可 


if (munmap((void *) shm->addr, shm->size) == -1) { 
ngx_log_error(NGX_LOG ALERT, shm->log, ngx_errno, "munmap(%p, %uz) 
failed", shm->addr, shm->size),; 


} 


Nginx 各 进程 间 共 享 数 据 的 主要 方式 就 是 使 用 共享 内 存 (在 使 用 共 
享 内 存 时 ，Nginx 一 般 是 由 master 进 程 创建 ， 在 masterj 进 程 fork 出 worker 
子 进 程 后 ， 所 有 的 进程 开始 使 用 这 块 内 存 中 的 数据 ) 。 在 开发 Nginx 模 
块 时 如 果 需 要 使 用 它 ， 不 妨 用 Nginx 已 经 封装 好 的 ngx_shm_alloc 方 法 
和 ngx_shm_free 方 法 ， 它 们 有 3 种 实现 (不 映射 文件 使 用 mmap 分 配 共 
至 内 存 、 以 /dev/zero 文 件 使 用 mmap 上 映射 共享 内 存 、 用 shmget 调 用 来 分 
配 共享 内 存 ) ， 对 于 Nginx 的 跨 平台 特性 考虑 得 很 周到 。 下 面 以 一 个 统 
计 HTTP 框 架 连 接 状 况 的 例子 来 说 明 共 至 内 存 的 用 法 。 


作为 Web 服 务 器 ，Nginx 具 有 统计 整个 服务 器 中 HITP 连 接 状况 的 
功能 (不 是 某 一 个 Nginx worker 进 程 的 状况 ， 而 是 所 有 worker 进 程 连接 
状况 的 总 和 ) 。 例 如 ， 可 以 用 于 统计 某 一 时 刻下 Nginx 已 经 处 理 过 的 连 
接 状况 。 下 面 定义 的 6 个 原子 变量 就 是 用 于 统计 
ngx_http_stub_status_module 模 块 连接 状况 的 ， 如 下 所 示 。 


// 已 经 建立 成 功 过 的 


TCP 连 接 数 


ngx_atomic_t ngx_stat_acceptedo0; 
ngx_atomic t *ngx_stat accepted = &ngx_stat_accepted0 
As# 尼 经 从 


ngx_cycle_t 核 心 结构 体 的 


free_connections 连 接 池 中 获取 到 


ngx_connection_t 对 象 的 活跃 连接 数 


SA/ 


ngx_atomic_t ngx_stat_active0 
ngx_atomic t  *ngx_stat_active = &ngx_Sstat_active0 
/* 连 接 建立 成 功 且 获 取 到 


ngx_connection_t 结 构 体 后 ， 已 经 分 配 过 内 存 池 ， 并 且 在 表示 初始 化 了 读 
/ 写 事件 后 的 连接 数 


过 


“/ 


ngx_atomic_t ngx_stat_handledo,; 
ngx_atomic t *ngx_stat_handled = &ngx_stat_handledo; 
// 已 经 由 


HTTP 模 块 处 理 过 的 连接 数 


ngx_atomic t ngx_stat_requests0; 
ngx_atomic_t *ngx_stat_requests = &ngx_stat_requestso0; 


// 1 


FE 在 接收 


TCP 流 的 连接 数 


ngx_atomic_t ngx_stat_readingg0 
ngx_atomic t  *ngx_stat_reading = &ngx_stat_reading0 


// 1 


E 在 发 送 


TCP 流 的 连接 数 


ngx_atomic_t ngx_stat_writingoO,; 
ngx_atomic t *ngx_stat writing = &ngx_stat_writingO; 


ngx_atomic {原子 变量 将 会 在 14.3 节 详细 介绍 ， 本 闻 仅 关注 这 6 个 
原子 变量 是 如 何 使 用 共享 内 存在 多 个 worker 进 程 中 使 用 这 些 统计 变量 


的 。 


size_t size, cl; 
ngx_shm_t shm; 


/* 计 算出 需要 使 用 的 共享 内 存 的 大 小 。 为 什么 每 个 统计 成 员 需要 使 


128 字 而 


尼 ? 这 似乎 太 大 了 ， 看 上 去 ， 每 个 


ngx_atomic_t 原 子 变 量 最 多 需要 


8 字 节 而 已 。 其 实 是 医 


Nginx 充 分 考虑 了 


CPU 的 二 级 缓存 。 在 


前 许多 


CPU 架构 下 缓存 行 的 大 小 都 是 


128 字 节 ， 而 下 面 需要 


统计 的 变量 都 是 访问 非常 频繁 的 成 员 ， 同 时 它们 占 


员 都 使 


128 字 节 存 放 的 形式 ， 


0 
cl = 128 
size = cl 
+ cl 
+ Cl 
大 是 又 丁 


这 样 速度 更 快 


/* ngx_accept_ mutex */ 
/* ngx_connection counter */ 
/* ngx_temp_number */ 


NGX_STAT_STUB 宏 后 才 会 统计 上 壕 


6 个 原子 变量 


#if (NGX_STAT_STUB) 


Size += cl 

cl 
cl 
cl 
cl 
Gl 


+ 十 十 十 ++ 


#endif 


/* ngx_stat_ accepted */ 
/* ngx_stat_handled */ 
/* ngx_stat_requests */ 
/* ngx_stat_active */ 

/* ngx_stat_reading */ 
/* ngx_stat writing */ 


// 初始 化 描述 


ngx_shm_t 结 构 体 


< 享 内 存 的 


shm.size = size,; 

shm.name.len = sizeof("nginx_shared zone"),; 
shm.name.data = (u_char *) "nginx_shared zone"; 
Shm.1og = cycle->1o0g,; 


// 开辟 一 块 共享 内 存 ， 共 享 内 存 的 大 小 为 


shm. size 


If (ngx_shm alloc(&shm) != NGX_OK) { 
return NGX_ERROR ， 


} 


// 共享 内 存 的 首 地 址 就 在 


shm.addr 成 员 中 


shared = shm.addr; 


// 原子 变量 类 型 的 


accept 锁 使 用 ] 


128 字 节 的 共享 内 存 


的 内 存 又 非常 少 ， 


所 以 采 


了 每 个 成 


ngx_accept_mutex_ptr = (ngx_atomic t *) Shared ， 
// ngx_accept_mutex 就 是 负载 均衡 锁 ， 


spin 值 为 


-1 则 是 告诉 


Nginx 这 把 锁 不 可 以 使 进程 进入 睡眠 状态 ， 详 见 
14 .8 节 
*/ 
ngx_accept_mutex.spin = (ngx_uint_t) -1; 


/* 原 子 变 量 类 型 的 
ngx_connection_counter 将 统计 所 有 建立 过 的 连接 数 (包括 主动 发 起 的 连接 ) 


*/ 

ngx_connection_ counter = (ngx_atomic t *) (shared + 1 * cl); 
#if (NGX_STAT_STUB) 

// 依次 初始 化 需要 统计 的 


6 个 原子 变量 ， 也 就 是 使 用 共享 内 存 作 为 原子 变量 


ngx_stat_accepted = (ngx_atomic t *) (shared + 3 * cl); 

ngx_stat_handled = (ngx_atomic t *) (shared + 4 * cl); 

ngx_stat_requests = (ngx_atomic t *) (shared + 5 * cl); 

ngx_stat_active = (ngx atomic t *) (shared + 6 * cl); 

ngx_stat_reading = (ngx_atomic t *) (shared + 7 * cl); 

ngx_stat_ writing = (ngx_atomic t *) (shared + 8 * cl); 
#endif 


这 6 个 统计 变量 在 初始 化 后 ， 在 处 理 请 求 的 流程 中 由 于 其 意义 不 
同 ， 所 以 其 值 会 有 所 变化 。 例 如 ， 在 HTTP 框 架 中 ， 刚 开始 接收 客户 端 
的 HTTP 请 求 时 使 用 的 是 ngx_http_init_request 方 法 ， 在 这 个 方法 中 就 会 
将 ngx_stat_reading 统 计 变 量 加 1， 表 示 正 处 于 接收 用 户 请 求 的 连接 数 加 
1， 如 下 所 示 。 


(void) ngx_atomic fetch add(ngx_stat_reading, 1); 


而 当 读 取 完 请 求 时 ， 如 在 ngx_http_process_request 方 法 中 ， 开 始 处 
理 用 户 请 求 (不 再 接收 TCP 消 息 ) ， 这 时 会 把 ngx_stat_reading 统 计 变 


量 减 1， 如 下 所 示 。 


(void) ngx_atomic_ fetch add(ngx_stat_reading, -1); 


这 6 个 统计 变量 都 是 在 关键 的 流程 中 进行 维护 的 ， 每 个 worker 进 程 
修改 的 都 是 共享 内 存 中 的 统计 变量 ， 它 们 对 于 整个 Nginx 服 务 来 说 是 全 
局 有 效 的 。ngx_http_stub_status_module 模 块 将 负责 在 接收 到 相应 的 
HTTP 查 询 请 求 后， 把 这 些 统计 变量 以 HTTP 啊 应 的 方式 发 送 给 客户 
端 。 该 模块 也 可 以 作为 14.3 节 原子 变量 的 使 用 案例 。 


14.3 ”原子 操作 


能 够 执行 原子 操作 的 原子 变量 只 有 整 型 ， 包 括 无 符号 整 型 
ngx_atomic_uint_t 和 有 符号 整 型 ngx_atomic_t， 这 两 种 类 型 都 使 用 了 


volatile 关 键 字 告诉 C 编 译 器 不 要 做 优化 。 


想 要 使 用 原子 操作 来 修改 、 获 取 整 型 变量 ， 目 然 不 能 使 用 加 诚 
号， 而 要 使 用 Nginx 提 供 的 两 个 方法 :ngx_atomic_cmp_set 和 
ngx_atomic_fetch_add。 这 两 个 方法 都 可 以 用 来 修改 原子 变量 的 值 ， 而 
ngx_atomic_cmp_set 方 法 同时 还 可 以 比较 原子 变量 的 值 ， 下 面具 体 看 
看 这 两 个 方法 。 
static ngx_inline ngx_atomic uint_t 


ngx_atomic_cmp_set(ngx_atomic _t *lock, ngx_atomic uint_t old, 
ngx_atomic_uint_t set) 


ngx_atomic_cmp_set 方 法 会 将 old 参 数 与 原子 变量 lock 的 值 做 比 
较 ， 如 果 它 们 相等 ， 则 把 lock 设 为 参数 set， 同 时 方法 返回 1， 如 果 它 们 
不 相等 ， 则 不 做 任何 修改 ， 返 回 0 。 


static ngx_inline ngx_atomic_int_t 
ngx_atomic_ fetch _ add(ngx_atomic t *value, ngx_atomic_ int_t add) 


ngx_atomic_fetch_add 方 法 会 把 原子 变量 value 的 值 加 上 参数 add， 
同时 返回 之 前 value 的 值 。 


在 Nginx 各 种 锁 的 实现 中 ， 可 以 看 到 原子 变量 和 这 两 个 方法 的 多 种 
用 法 。 


即使 操作 系统 的 内 核 无 法 提供 原子 性 的 操作 ， 那 么 Nginx 也 会 对 上 
述 两 个 方法 提供 一 种 实现 ， 这 在 14.3.1 节 中 会 简单 说 明 ; 对 于 各 种 硬件 
体系 架构 ， 原 子 操作 的 实现 不 尽 相 同 ， 在 14.3.2 市 中 将 会 以 最 第 见 的 
X86 架构 为 例 ， 说 明 Nginx 古 怎样 实现 上 述 两 个 原子 操作 方法 的 。 在 
14.3.3 节 ， 介 绍 Nginx 封 装 的 ngx_spinlock 自 旋 锁 是 怎样 使 用 原子 变量 实 
现 的 。 


14.3.1 不 支持 原子 库 下 的 原子 操作 


jk 


当 无 法 实现 原子 操作 时 ， 就 只 能 用 volatile 关 键 字 在 C 语 言 级 别 上 
模拟 原子 操作 了 。 事 实 上 ， 目 前 绝 大 多 数 体系 架构 都 是 支持 原子 操作 
有 的， 给 出 这 一 节 内 容 更 多 的 是 方便 读者 理解 ngx_atomic_cmp_set 方 法 
和 ngx_atomic_fetch_add 方 法 的 意义 。 先 来 看 看 ngx_atomic_cmp_set 方 
法 的 实现 ， 如 下 所 示 。 


static ngx_inline ngx_atomic_ uint_t 
ngx_atomic_cmp_set(ngx_atomic t *lock, ngx_atomic uint_t old, 
ngx_atomic_uint_t set) 
{ 
// 当 原 子 变量 


lock 与 


old 相 等 时 ， 才 能 把 


set 设 置 到 


lock 中 并 返回 


1 
If (*lock == old) { 
*lock = set,; 
return 1; 


} 
// 若 原 子 变量 


lock 与 
01d 不 相等 ， 则 返回 
0 


} 


return 0,; 


ngx_atomic_fetch_add 方 法 的 实现 也 很 简单 ， 如 下 所 示 。 


static ngx_inline ngx_atomic_int 七 
ngx_atomic_fetch_add(ngx_atomic t *value, ngx_atomic_ int_t add ) 


{ 


ngx_atomic_ int t old; 
// 将 原子 变量 


value 加 上 


add 值 之 后 ， 再 返回 原先 
value 的 值 
old = *value; 


*value += add; 
return old; 


14.3.2 ” x86 架构 下 的 原子 操作 


Nginx 要 在 源 代码 中 实现 对 整 型 的 原子 操作 ， 目 然 必须 通过 内 联 息 
编 语言 直接 操作 硬件 才能 做 到 ， 本 市 以 基于 x86 的 SMP 多 核 架 构 为 例 来 
看 看 Nginx 是 如 何 实现 这 两 个 基本 的 原子 操作 的 (由 于 参考 着 x86 架 构 
下 的 实现 即 可 以 人 简单 地 推导 出 其 他 架构 下 的 实现 ， 故 其 他 架构 下 的 原 
子 操作 实现 方法 不 再 一 一 说 明 ) 。 


使 用 GCC 编 译 如 在 C 语 言 中 杉 入 汇编 语言 的 方式 是 使 用 _asm 关 
键 字 ， 如 下 所 示 。 


asm_ volatile ( 汇编 语句 部 分 


: 输出 部 分 


: 输入 部 分 


: 破坏 描述 部 分 
/* 可 选 


以 上 加 入 的 volatile 关 键 字 用 于 限制 GCC 编译 需 对 这 段 代码 做 优 
化 


这 段 内 联 的 汇编 语言 包括 4 个 部 分 。 


(1) 汇编 语句 部 分 


引号 中 所 包含 的 汇编 语句 可 以 直接 用 占 位 符 % 来 引用 C 语 言 中 的 变 


本 
量 (最 多 10 个 ，%0~%9) 。 
下 面 简单 介绍 一 下 随后 用 到 的 两 个 汇编 语句 ， 先 来 看 看 cmpxchglr, 


[m] 这 个 语句 ，Nginx 源 代码 中 对 这 一 汇编 语句 有 一 段 伪 代码 注释 ， 如 
下 太 A 


// 如 果 
eax 寄 存 器 中 的 值 等 于 


m 
If (eax == [m]) { 
// 将 


zf 标志 位 设 为 


eax 寄 存 器 中 的 值 不 等 于 


m 
} else { 
// zf 标志 位 设 为 


eax 和 寄存 器 中 的 值 设 为 


m 


} 


eax = [m]; 


从 上 面 这 段 伪 代码 可 以 看 出 ，cmpxchgl r,[m] 语 句 首 和 完 会 用 m 比 较 
eax 寄 存 需 中 的 值 ， 如 果 相 等 ， 则 把 mm 的 值 设 为 r， 同 时 将 zf 标志 位 设 为 


1; 否则 将 zf 标志 位 设 为 0。 


再 看 一 个 语句 seterm]， 它 正好 配合 着 上 面 的 cmpxchgl 语 句 使 用 ， 
这 里 不 妨 人 简单 地 认为 它 的 作用 就 是 将 zf 标志 位 中 的 0 或 者 1 设置 到 m 


oO 


(2) 输出 部 分 
这 部 分 可 以 将 寄存 右 中 的 值 设置 到 C 语 言 的 变量 中 。 
(3) 输入 部 分 
可 以 将 C 语 言 中 的 变量 设置 到 寄存 器 中 。 
(4) 破坏 描述 部 分 
通知 编译 右 使 用 了 哪些 寄存 右 、 内 存 。 


简单 了 解 了 了 GCC 如何 内 联 沪 编 语 言 后 ， 下 面 来 看 看 
ngx_atomic_cmp_set 方 法 的 实现 ， 如 下 所 示 。 


static ngx_inline ngx_atomic_ uint_t 
ngx_atomic_cmp_set(ngx_atomic t *lock, ngx_atomic uint_t old, 
ngx_atomic uint_t set) 


u_char res; 


// 在 


C 语 言 中 骸 入 汇编 语言 


asm _ volatile ( 


// 多 核 架 构 下 首先 锁 住 总 线 


lock; 
// 将 


*1ock 的 值 与 
eax 寄 存 器 中 的 
old 相 比较 ， 如 果 相 等 ， 则 置 


*]ock 的 值 为 
set 
"cmpxchgl %3, %1;" 
// cmpxchgl 的 比较 车 是 相等 ， 则 把 
zf 标志 位 
1 写 入 


res 变 量 ， 否 则 


res 为 


0 
"Sete %0;" 
: "=a" (res) : "m"”(*]lock)，"a" (old), "r" (set) : "cc", "memory"); 
return res; 


} 


现在 简单 地 说 明 一 下 上 述 代码 ， 在 嵌入 汇编 语言 的 输入 部 
分 ，"m"(*lock) 表 示 3]ock 变 量 是 在 内 存 中 ， 损 作 *lock 时 直接 通过 内 存 
(不 使 用 寄存 器 ) 处 理 ， 而 "a"(old) 表 示 把 old 变 量 写 入 eax 寄 存 器 
中 ，"r"(set) 表 示 把 set 变 量 写 入 通用 寄存 器 中 ， 这 些 都 是 在 为 cmpxchgl 
语句 做 准备 。“cmpxchgl%3,%1” 相 当 于 “cmpxchglset*lock” (含义 参照 
上 面 介绍 过 的 伪 代 码 ) 。 这 3 行 汇 编 语句 的 意思 如 下 : 首先 锁 住 总 线 防 
止 多 核 的 并 发 执行 ， 接 着 判断 原子 变量 *lock 与 old 值 是 否 相等 ， 若 相 
等 ， 则 把 *lock 值 设 为 set， 同 时 设 res 为 1， 方 法 返回 ， 若 不 相等 ， 则 设 
res 为 0， 方 法 返回 。 


在 了 解 ngx_atomic_fetch_add 方 法 前 ， 再 介绍 一 个 汇编 语句 xaddl 。 
下 面 先 来 看 看 Nginx 对 “xaddlr[m]” 语 句 做 的 伪 码 注释 ， 如 下 所 示 。 


temp = [m]; 
[m] += r; 
r = temp; 


可 以 看 到 ，xaddl 执 行 后 [m] 值 将 为 r 和 [m] 之 和 ， 而 r 中 的 值 为 原 [m] 
值 。 现 在 看 看 ngx_atomic_fetch_add 方 法 是 如 何 实现 的 ， 如 下 所 示 。 


static ngx_inline ngx_atomic_int_t 
ngx_atomic fetch add(ngx_atomic t *value, ngx_atomic_ int_t add) 
{ 

_asm _ volatile ( 

// 首先 锁 住 总 线 


"lock;" 
// *value 的 值 将 会 等 于 原先 


*Value 值 与 
add 值 之 和 ， 而 
add 为 原 
*Value 值 
"Xadd1 %0, %1;" 
:"+r" (add) : "m" (*value) : "cc", "memory"); 


return add,; 


} 


有 可见，ngx_atomic_fetch_add 将 使 得 *value 原 子 变量 的 值 加 上 add， 
同时 返回 原先 *value 的 值 。 


14.3.3 ”上 自 旋 锁 


基于 原子 操作 ，Nginx 实 现 了 一 个 目 旋 锁 。 目 旋 锁 是 一 种 非 睡 眠 
锁 ， 也 吏 是 说 ， 某 进程 如 采 试 图 获得 目 旋 锁 ， 当 发 现 锁 已 经 被 其 他 进 
程 获得 时 ， 那 么 不 会 使 得 当前 进程 进入 睡眠 状态 ， 而 是 始终 保持 进程 
在 可 执行 状态 ， 每 当 内 核 调度 到 这 个 进程 执行 时 吏 持 续 检 查 是 人 否 可 以 
获取 到 锁 。 在 拿 不 到 锁 时 ， 这 个 进程 的 代码 将 会 一 直 在 目 旋 锁 代 码 处 
执行 ， 直 到 其 他 进程 释放 了 锁 且 当前 进程 获取 到 了 锁 后 ， 代 码 才 会 继 
续 问 下 执行 。 


可 见 ， 自 旋 锁 主要 是 为 多 处 理 器 操作 系统 而 设置 的 ， 它 要 解决 的 

享 资源 保护 场景 就 是 进程 使 用 锁 的 时 间 非 常 短 (如 果 锁 的 使 用 时 间 
很 久 ， 自 旋 锁 会 不 太 合适 ， 那 么 它 会 占用 大 量 的 CPU 资源 ) 。 在 14.6 
节 和 14.7 节 介绍 的 两 种 睡 眼 锁 会 导致 进程 进入 睡 眼 状态 。 睡 眼 锁 与 非 
睡眠 锁 应 用 的 场景 不 同 ， 如 果 使 用 锁 的 进程 不 太 希 望 自己 进入 睡眠 状 
仿 ， 特 别 它 处 理 的 是 非常 核心 的 事件 时 ， 这 时 束 应 该 使 用 目 旋 锁 ， 其 
实 大 部 分 情况 下 Nginx 的 worker 进 程 最 好 都 不 要 进入 睡眠 状态 ， 因 为 它 
非常 繁忙 ， 在 这 个 进程 的 epoll 上 可 能 会 有 十 万 甚至 百 万 的 TCP 连 接 等 
待 着 处 理 ， 进 程 一 旦 睡眠 后 必须 等 待 其 他 事件 的 唤醒 ， 这 中 间 极 其 频 
繁 的 进程 间 切 换 带 来 的 负载 消耗 可 能 无 法 让 用 户 接受 。 


人 @@ 注音 自 旋 锁 对 于 单 处 理 器 操作 系统 来 说 一 样 是 有 效 的 ， 不 
进入 睡眠 状态 并 不 意味 着 其 他 可 执行 状态 的 进程 得 不 到 执行 。Linux 内 
核 中 对 于 每 个 处 理 器 都 有 -一 个 运行 队列 ， 自 旋 锁 可 以 仅仅 调整 当前 进 


程 在 运行 队列 中 的 顺序 ， 或 者 调整 进程 的 时 间 片 ， 这 都 会 为 当前 处 理 
右上 的 其 他 进程 提供 被 调度 的 机 会 ， 以 使 得 锁 被 其 他 进程 释放 。 


用 户 可 以 从 锁 的 使 用 时 间 长 短 角 度 来 选择 使 用 哪 一 种 锁 。 当 锁 的 
使 用 时 间 很 短 时 ， 使 用 目 旋 锁 非常 合适 ， 尤 其 是 对 于 现在 普遍 存在 的 
多 核 处 理 器 来 说 ， 这 样 的 开销 最 小 。 而 如 果 锁 的 使 用 时 间 很 长 时 ， 那 
和 一旦 进程 拿 不 到 锁 束 不 应 该 再 执行 任何 操作 了 ， 这 时 应 该 使 用 睡眠 
锁 将 系统 资源 释放 给 其 他 进程 使 用 。 男 外 ， 如 琳 进 程 拿 不 到 锁 ， 可 能 
只 会 导致 某 一 类 请 求 (不 是 进程 上 的 所 有 请 求 ) 不 能 继续 执行 ， 而 
epoll 上 的 其 他 请 求 还 是 可 以 执行 的 ， 这 时 应 该 选用 非 阻 塞 的 互 乒 锁 ， 
而 不 能 使 用 目 旋 锁 。 


下 面 介 绍 基于 原子 操作 的 目 旋 锁 方 法 ngx_spinlock 是 如 何 实现 的 。 
它 有 3 个 参数 ， 其 中 ，lock 参 数 束 古 原 于 变量 表达 的 锁 ， 当 lock 值 为 0 时 
表示 锁 生 被 释放 的 ， 而 lock 值 不 为 0 时 则 表示 锁 已 经 被 某 个 进程 持 有 
了 ; value 人 参数 表示 希望 当 锁 没 有 被 任何 进程 择 有 时 〈 也 就 是 lock 值 为 
0) ， 把 lock 值 设 为 value 表 示 当 前 进程 持 有 了 锁 ;， 第 三 个 参数 spin 表 示 
在 多 人 处理 器 系统 内 ， 当 ngx_spinlock 方 法 没有 拿 到 锁 时 ， 当 前 进程 在 内 
核 的 一 次 调度 中 ， 该 方法 等 待 其 他 处 理 硕 释放 锁 的 时 间 。 下 面 来 看 一 
下 它 的 产 代码 。 


void ngx_spinlock(ngx_atomic t *]lock, ngx_atomic_ int _t value, ngx_uint_t spin) 


ngx_uint_t i, n; 
// 无 法 获取 锁 时 进程 的 代码 将 一 直 在 这 个 循环 中 执行 


for (;; ) 区 
// lock 为 


9 时 表示 锁 是 没有 被 其 他 进程 持 有 的 ， 这 时 将 


lock 值 设 为 


Value 参数 表 示 当 前 进程 持 有 了 锁 


if (*lock == 0 && ngx_atomic_cmp_set(1Lock，0，Vvalue)) { 
// 获取 到 锁 后 


ngx_spinlock 方 法 才 会 返回 


return; 


} 
// ngx_ncpu 是 处 理 器 的 个 数 ， 当 它 大 于 


1 时 表示 处 于 多 处 理 器 系统 中 


nn 


If (ngx_ncpu > 1) { 
/* 在 多 处 理 器 下 ， 更 好 的 做 法 是 当前 进程 不 要 立刻 “让 出 * 正 在 使 用 的 


CPU 处 理 器 ， 而 是 等 待 一 段 时 间 ， 看 看 其 他 处 理 器 上 的 进程 是 否 会 释放 锁 ， 这 会 减少 进程 间 切 换 的 次 数 


4 


) { 
/* 注 意 ， 随 着 等 待 的 次 数 越 来 越 多 ， 实 际 去 检查 
lock 是 否 释 放 的 频繁 会 越 来 越 小 。 为 什么 会 这 样 呢 ?因为 检查 
lock 值 更 消耗 


CPU， 而 执行 


ngx_cpu_pause 对 于 


CPU 的 能 耗 来 说 是 很 省 电 的 


*/ 
for (i = 0; i < Nn; i++) { 
/*ngx_cpu_pause 是 在 许多 架构 体系 中 专门 为 了 自 旋 锁 而 提供 的 指令 ， 它 会 告诉 
CPU 现 在 处 于 自 旋 锁 等 待 状态 ， 通 常 一 些 


CPU 会 将 自己 置 于 节能 状态 ， 降 低 功 耗 。 注 意 ， 在 执行 


ngx_cpu_pause 后 ， 当 前 进程 没有 “让 出 * 正 使 用 的 处 理 器 


< 
ngx_cpu_pause( ); 


} 
/* 检 查 锁 是 否 被 释放 了 ， 如 果 


lock 值 为 


09 且 释 放 了 锁 后 ， 就 把 它 的 值 设 为 
value， 当 前 进程 持 有 锁 成 功 并 返回 


六 
if (*lock == 0 && ngx_atomic_cmp_set(1Lock，0，Vvalue)) { 
return; 
} 
} 


/* 当 前 进程 仍然 处 于 可 执行 状态 ， 但 暂 
程 ， 这样， 在 进程 被 内 核 再 次 调度 时 ， 在 


for 循 环 代码 中 可 以 期 望 其 他 进程 释放 锁 。 注 意 ， 不 同 的 内 核 版 本 对 于 


二“ 让 出 ?处 理 器 ， 使 得 处 理 器 优先 调度 其 他 可 执行 状态 的 进 


五 


LC 
沪 
由 
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sched_yield 系 统 调用 的 实现 可 能 是 不 同 的 ， 但 它们 的 目的 都 是 暂时 “让 出 ” 


*/ 
ngx_sched_yield( ); 
})} 


释放 锁 时 需要 Nginx 模 块 通过 ngx_atomic_cmp_set 方 法 将 原子 变量 


lock 值 设 为 0。 


可 以 看 到 ，ngx_spinlock 方 法 是 非常 高 效 的 目 旋 锁 ， 它 充分 考虑 了 
单 处 理 紫 和 多 处 理 右 的 系统 ， 对 于 持 有 锁 时 间 非 常 短 的 场景 很 有 效 


14.4 Nginx 频 道 


ngx_channel_ {频道 是 Nginx master 进 程 与 worker 进 程 之 间 通 信 的 党 
用 工具 ， 它 是 使 用 本 机 套 接 字 实 现 的 。 下 面 先 来 看 看 socketpair 方 法 ， 
它 用 于 创建 父子 进程 间 使 用 的 套 接 字 。 


int socketpair(int d, int type, int protocol, int sv[2]); 


这 个 方法 可 以 创建 一 对 关联 的 套 接 字 sv[2]。 下 面 依次 介绍 它 的 4 
个 参数 : 参数 d 表 示 域 ， 在 Linux 下 通常 取 值 为 AF_UNIX; type 取 值 为 
SOCK_STREAM 或 者 SOCK_DGRAM， 它 表示 在 套 接 字 上 使 用 的 是 
TCP 还 是 UDP; protocol 必 须 传递 0;，sv[2] 是 一 个 含有 两 个 元 素 的 整 型 
数组 ， 实 际 上 就 是 两 个 套 接 字 。 当 socketpair 返 回 0 时 ，sv[2] 这 两 个 套 
过 字 创 建成 功 ， 否 则 socketpair 返 回 -1 表示 失败 。 


当 socketpair 执 行 成 功 时 ，sv[2] 这 两 个 父 接 字 具 备 下 列 关 系 : 问 
sv[0] 套 接 字 写 入 数据 ， 将 可 以 从 sv[1] 僚 接 字 中 读 取 到 刚 写 入 的 数据 ; 
同样 ， 回 sy[1] 套 接 字 写 入 数据 ， 也 可 以 从 sv[0] 中 读 取 到 写 入 的 数据 。 
， 在 父 、 子 进程 通信 前 ， 会 完 调用 socketpair 方 法 创建 这 样 一 组 套 
， 在 调用 fork 方 法 创建 出 子 进程 后 ， 将 会 在 父 进 程 中 关闭 sv[1] 套 
， 仅 使 用 sv[0] 套 接 字 用 于 同 子 进程 发 送 数据 以 及 接收 子 进程 发 送 
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来 的 数据 ， 而 在 子 进程 中 则 关闭 sv[0] 套 接 字 ， 仅 使 用 sv[1] 套 接 字 婚 可 
以 接收 父 进程 发 来 的 数据 ， 也 可 以 向 父 进程 发 送 数 据 。 


再 来 介绍 一 下 ngx_channel t 频 道 。ngx_channel t 结 构 体 是 Nginx 定 
义 的 master 父 进程 与 worker 子 进程 间 的 消息 格式 ， 如 下 所 示 。 


typedef Struct 区 
/ 传递 的 


TCP 消 息 中 的 命令 


ngx_uint_t command; 
// 进程 


ID， 一 般 是 发 送 命令 方 的 进程 
ID 


ngx_pid_t pid; 
// 表示 发 送 命 令 方 在 


ngx_processes 进 程 数组 间 的 序号 


ngx_int_t slot; 
// 通信 的 套 接 字句 柄 


ngx_fd fd; 
} ngx_channel_t; 
这 个 消息 的 格式 似乎 过 于 人 简单 了 ， 没 错 ， 因 为 Nginx 仅 用 这 个 频道 
同步 masterj 进 程 与 worker 进 程 间 的 状态 ， 这 点 从 针对 command 成 员 已 经 
定义 的 命令 就 可 以 看 出 来 ， 如 下 所 示 。 


// 打开 频道 ， 使 用 频道 这 种 方式 通信 前 必须 发 送 的 命令 


#define NGX_CMD_OPEN_CHANNEL 1 
// 关闭 已 经 打开 的 频道 ， 实 际 上 也 就 是 关闭 套 接 字 


#define NGX_CMD_CLOSE_CHANNEL 2 


// 要 求 接收 方正 常 地 退出 进程 


#define NGX_CMD_QUIT 3 
// 要 求 接收 方 强制 地 结束 进程 


#define NGX_CMD_TERMINATE 4 
// 要 求 接收 方 重新 打开 进程 已 经 打开 过 的 文件 


#define NGX_CMD_ REOPEN 5 


在 8.6 太 我 们 介绍 过 master 进 程 是 如 何 监控 、 管 理 worker 子 进程 
的 ， 那 图 8-8 中 的 master 又 是 如 何 启 动 、 停 止 worker 子 进程 的 呢 ? 正 是 
ee 即 每 次 要 派生 一 个 子 进程 之 

， 都 会 移 调 用 socketpair 方 法 。 在 Nginx 派 生子 进程 的 
ea 会 首先 派生 基于 TCP 的 套 接 字 ， 如 下 所 


修 ° 


ngx_pid_t ngx_spawn_process(ngx_cycle t *cycle, ngx_spawn_proc_pt proc, void 
*data, char *name, ngx_int_t respawn) 


{ 


// ngx_processes[s].channel 数 组 正 是 将 要 用 于 父 、 子 进程 间 通 信 的 套 接 字 对 


If (socketpair(AF_UNIX, SOCK_STREAM, 0, ngx_processes[s].channel) == -1) 
return NGX_INVALID_PID ， 

} 

// 接 下 来 会 把 


channe1 套 接 字 对 都 设置 为 非 阻 塞 模式 


上 段 代 码 提 到 的 ngx_processes 数 组 定义 了 Nginx 服 务 中 所 有 的 进 
程 ， 包 括 master 进 程 和 worker 进 程 ， 如 下 所 示 。 


#define NGX_MAX_PROCESSES 1024 
// 虽然 定义 了 


NGX_MAX_PROCESSES 个 成 员 ， 但 已 经 使 用 的 元 素 仅 与 启动 的 进程 个 数 有 关 


ngx_process_t ngx_processes[NGX_MAX_PROCESSES] ， 


它 的 类 型 是 ngx_process t， 对 于 频道 来 说 ， 这 个 结构 体 只 关心 它 
的 channel 成 员 。 


typedef struct { 


// socketpair 创 建 的 套 接 字 对 


ngx_socket_t channel[2]; 
} ngx_process_t; 


如 何 使 用 频道 发 送 ngx_channel_t 消 息 呢 ? Nginx 封 装 了 4 个 方法 ， 
首先 来 看 看 用 于 发 送 消息 的 ngx_write_channel 方 法 。 


ngx_int_t ngx_write channel(ngx_socket_t s, ngx_channel t *ch，Size_t size, 
ngx_log_t *10g); 


这 里 的 $ 参 数 是 要 使 用 的 TCP 套 接 字 ，ch 人 参数 是 ngx_channel t 类 型 
的 消息 ，size 参 数 是 ngx_channel_t 结 构 体 的 大 小 ，log 参 数 是 日 志 对 
象 o 


再 来 看 看 读 取消 息 的 方法 ngx_read_channel。 


ngx_int_t ngx_read_channel(ngx_socket_t s, ngx_channel t *ch, size_t size, 
ngx_log_t *1og) ， 


这 里 的 参数 意义 与 ngx_write_channel 方 法 完全 相同 ， 只 是 要 注意 s 
套 接 字 ， 它 与 发 送 方 使 用 的 s 套 接 字 是 配对 的 。 例 如 ， 在 Nginx 中 ， 目 
前 仅 存 在 master 进 程 向 workerj 埋 程 发 送 消息 的 场景 ， 这 时 对 于 
socketpair 方 法 创建 的 channel[2] 套 接 字 对 来 说 ，masterj 埋 程 会 使 用 
channel[0] 套 接 字 来 发 送 消 息 ， 而 worker 进 程 则 会 使 用 channel[1] 套 接 字 
来 接收 消息 。 


worker 进 程 是 怎样 调度 ngx_read_channel 方 法 接收 频道 消息 呢 ? 毕 
况 Nginx 是 单线 程 程序 ， 这 唯一 的 线程 还 在 同时 处 理 大 量 的 用 户 请 求 
呢 ! 这 时 就 需要 使 用 ngx_add_channel_event 方 法 把 接收 频道 消息 的 套 
接 字 添加 到 epol 中 了 ， 当 接收 到 父 进程 消 轧 时 子 进 程 会 通过 epoll 的 事 
件 回调 相应 的 handler 方 法 来 处 理 这 个 频道 消 电 ， 如 下 所 示 。 


ngx_int_t ngx_add_ channel event(ngx_cycle t *cycle，ngx_fd t fd, 
ngx_int_t event, ngx_event_handler_pt handler); 


cycle 参 数目 然 是 每 个 Nginx 进 程 必须 具备 的 ngx_cycle_t 核 心 结 构 
体 ; fd 参数 束 是 上 面 说 过 的 需要 接收 消息 的 套 接 字 ， 对 于 worker 子 进 
程 来 说 ， 束 是 对 应 的 channel[1] 套 接 字 ;，event 参 数 是 需要 检测 的 事件 类 
型 ， 在 上 述 场景 下 必然 是 EPOLLIN; handler 参 数 指向 的 方法 就 是 用 于 


关 道 消息 的 方法 ，Nginx 定 义 了 一 个 ngx_channel _ handler 方 法 用 于 


读 取 频 道 请 ， 
处 理 频 道 消 轧 。 


当 进程 希望 关闭 这 个 频道 通信 方式 时 ， 可 以 调用 
ngx_close_channel 方 法 ， 它 会 关闭 这 对 套 接 字 ， 如 下 所 示 。 


void ngx_close_ channel(ngx_fd_t *fd, ngx_log_t *1]0g); 


参数 fd 就 是 上 面 说 过 的 channel[2] 仁 接 字 数组 。 


实际 上 ， 基 于 本 机 TCP 的 套 接 字 可 以 进行 复杂 的 双 工 通信 ， 虽 然 
目前 Nginx 仅 用 于 帮助 master 进 程 管理 worker 进 程 的 状态 ， 但 完全 可 以 
轻易 地 进行 改造 ， 使 之 满足 复杂 的 进程 则 通信 和 需求 。 


14.5 “信和 号 


Linux 提 供 了 以 信号 传递 进程 间 消 居 的 机 制 ，Nginx 在 管理 master 
进程 和 worker 进 程 时 大 量 使 用 了 信和 号。 什么 是 信号 ? 它 是 一 种 非常 短 
的 消息 ， 短 到 只 有 一 个 数字 。 在 中 文 译名 中 ， 信 号 相 比 下 文 将 要 介绍 
的 信号 量 只 少 了 一 个 字 ， 但 它们 完全 是 两 个 概念 ， 信 和 号 量 仅 用 于 同步 
代码 段 ， 而 信号 则 用 于 传递 消 轧 。 一 个 进程 可 以 同 另 外 一 个 进程 或 者 
另外 一 组 进程 发 送信 号 消 思 ， 通 知 目标 进程 执行 特定 的 代码 。 


Linux 定 义 的 前 31 个 信号 是 最 常用 的 ，Nginx 则 通过 重 定 义 其 中 一 
些 信号 的 处 理 方法 来 使 用 信号 ， 如 接收 到 SIGUSR1 信 和 号 就 意味 着 需要 
重新 打开 文件 。 使 用 信号 时 Nginx 定 义 了 一 个 ngx_signal t 结 构 体 用 于 
描述 接收 到 信号 时 的 行为 ， 如 下 所 示 。 


typedef struct { 
// 需要 处 理 的 信号 


ea 


int signo; 
// 信号 对 应 的 字符 串 名 称 


char *signame; 
// 这 个 信号 对 应 着 的 


Nginx 命 令 


char *name ， 


// 收 到 


signo 信 号 后 就 会 回调 


handler 方 法 


void (*handler)(int signo); 
} ngx_signal_t; 


另外 ，Nginx 还 定义 了 一 个 数组 ， 用 来 定义 进程 将 会 处 理 的 所 有 信 
号 ° 例如 : 


#define NGX_RECONFIGURE_SIGNAL HUP 
ngx_signal t signals[] = { 

{ ngx_signal value(NGX_ RECONFIGURE_SIGNAL), 
"SIG" ngx_value(NGX_ RECONFIGURE_SIGNAL), 
"reload", 
ngx_signal_handler }, 


上 面 的 例子 意味 着 在 接收 到 SIGHUP 信 号 后 ， 将 调用 
ngx_signal_handler 方 法 进行 处 理 ， 以 便 重新 读 取 配置 文件 ， 或 者 说 ， 
当 收 到 用 户 发 来 的 如 下 命令 时 : 


./Nginx -s reload 


这 个 新 启动 的 Nginx 进 程 会 同 实 际 运行 的 Nginx 服 务 进程 发 送 SIGHUP 
信号 (执行 这 个 命令 后 拉 起 的 Nginx 进 程 并 不 会 重新 启动 服务 器 ， 而 是 
仅 用 于 发 送信 号 ， 在 ngx_get_options 方 法 中 会 重 置 ngx_signal 全 局 变 
量 ， 而 main 方 法 中 检查 到 其 非 O 时 就 会 调用 ngx_signal_process 方 法 疝 正 
在 运行 的 Nginx 服 务 发 送信 号 ， 之 后 main 方 法 就 会 返回 ， 新 启动 的 
Nginx 进 程 退 出 ) ， 这 样 运行 中 的 服务 进程 也 会 调用 ngx_signal_handler 
方法 来 处 理 这 个 信和 号。 


在 定义 了 ngx_signal_t 类 型 的 signals 数 组 后 ，ngx_init_signals 方 法 
会 初始 化 所 有 的 信号 ， 如 下 所 示 。 


ngx_int_t ngx_init_signals(ngx_log_t *10g) 
{ 


ngx_signal _t *sig; 
// Linux 内 核 使 用 的 信号 


struct sigaction sa; 


// 遍历 


signals 数 组 ， 处 理 每 一 个 


ngx_signal t 类 型 的 结构 体 


for (sig = signals; sig->signo != ©; Sig++) { 
ngx_memzero(&sa, sizeof(struct sigaction)); 


// 设置 信号 的 处 理 方法 为 


handler 方 法 


sa.sa_handler = sig->handler; 
// 将 


sa 中 的 位 全 部 置 为 


sigemptyset(&sa.sa mask); 
口 


Linux 注 册 信号 的 回调 方法 


if (sigaction(sig->signo, &sa, NULL) == -1) { 
ngx_log_error(NGX_LOG_ EMERG, log, ngx_errno, 
"sigaction(%s) failed", sig->signame); 
return NGX_ERROR ， 
} 


} 
return NGX_OK; 


这 样 进程 束 可 以 处 理 信号 了。 如 果 用 户 锅 望 Nginx 处 理 更 多 的 信 
号 ， 那么 可 以 直接 癌 signals 数 组 中 添加 新 的 ngx_signal_t 成 员 。 


14.6 ”信号 量 


信号 量 与 信号 不 同 ， 它 不 像 信号 那样 用 来 传递 消 轧 ， 而 是 用 来 保 
证 两 个 或 多 个 代码 段 不 被 并 发 访问 ， 是 一 种 保证 共 主 资源 有 序 访 问 的 
工具 。 使 用 信号 量 作为 互 斤 锁 有 可 能 导致 进程 睡眠 ， 因 此 ， 要 刘 慎 使 
用 ， 特 别 是 对 于 Nginx 这 种 每 一 个 进程 同时 处理 着 数 以 万 计 请 求 的 服务 
右 来 说 ， 这 种 导致 睡眠 的 操作 将 有 可 能 造成 性 能 大 幅 降 低 。 


会 介绍 这 种 用 法 。 定 义 一 个 sem_t 类 型 的 变量 后 ， 即 可 围绕 
着 它 使 用 信号 量 。 使 用 前 ， 先 要 调用 sem_init 方 法 初始 化 信号 量 ， 如 下 
所 过 


int sem init(sem t *sem, int pshared, unsigned int Value ) ; 


其 中 ， 参 数 sem 即 为 我 们 定义 的 信号 量 ， 而 参数 pshared 将 指明 sem 
信和 号 量 是 用 于 进程 间 同 步 还 是 用 于 线程 间 同 步 ， 当 pshared 为 0 时 表示 
线程 间 同 步 ， 而 pshared 为 1 时 表示 进程 间 同 步 。 由 于 Nginx 的 每 个 进程 
都 是 单线 程 的 ， 因 此 将 参数 pshared 设 为 1 即 可 。 人 参数 value 表 示 信 和 号 量 
sem 的 初始 值 。 下 面 看 看 在 ngx_shmtx_create 方 法 中 是 如 何 初始 化 信和 号 
量 的 。 


ngx_int_t ngx_shmtx_create(ngx_shmtx_t *mtx, void *addr, u_char *name) 


#if (NGX_ HAVE_ POSIX_ SEM) 
2 - 听 . 下 


// 信号 量 


mtx->sem 初 始 化 为 


90， 用 于 进程 间 通 信 
if (sem init(&mtx->sem, 1, 0) == -1) { 
ngx_log_error(NGX_LOG ALERT, ngx_cycle->log, ngx_errno, 
"sem_init() failed"),; 
} else { 
mtx->semaphore = 1; 
} 
#endif 


return NGX_OK; 
} 


ngx_shmtx_t 结 构 体 将 会 在 14.8 节 中 介绍 。 可 以 看 到 ， 在 定义 了 
NGX_HAVE_POSIX_SEM 宏 后 ， 将 开始 使 用 信号 量 。 另 外 ， 
sem_destroy 方 法 可 以 销毁 信号 量 。 例 如 : 


void ngx_shmtx_destory(ngx_shmtx_t *mtx) 


{ 
#if (NGX_HAVE_ POSIX_ SEM) 
if (mtx->semaphore) { 
if (sem destroy(&mtx->sem) == -1) { 
ngx_log_error(NGX_LOG ALERT, ngx_cycle->log, ngx_errno, 
"sem_ destroy() failed"); 


} 
#endif 


信号 量 是 如 何 实现 互 斤 锁 功 能 的 呢 ? 例如 ， 最 初 的 信号 量 sem 值 
为 0， 调 用 sem_post 方 法 将 会 把 sem 值 加 1， 这 个 操作 不 会 有 任何 阻塞; 
调用 sem_wait 方 法 将 会 把 信号 量 sem 的 值 减 1， 如 果 sem 值 已 经 小 于 或 
等 于 0 了 ， 则 阻塞 住 当前 进程 (进程 会 进入 睡眠 状态 ， 直 到 其 他 进程 


将 信号 量 sem 的 值 改 变 为 正 数 后 ， 这 时 才能 继续 通过 将 sem 减 1 而 使 得 
当前 进程 继续 辐 下 执行 。 因 此 ，sem_post 方 法 可 以 实现 解锁 的 功能 ， 
而 sem_wait 方 法 可 以 实现 加 锁 的 功能 


例如 ，ngx_shmtx_lock 方 法 在 加 锁 时 ， 有 可 能 到 使 用 sem_wait 的 分 
文 去 试图 获得 锁 ， 如 下 所 示 。 


void ngx_shmtx_lock(ngx_shmtx_t *mtx) 


// 如 果 没 有 拿 到 锁 ， 这 时 


Nginx 进 程 将 会 睡眠 ， 直 到 其 他 进程 释放 了 锁 


while (sem wait(&mtx->sem) == -1) { 


} 


ngx_shmtx_lock 方 法 会 在 14.8 节 详细 说 明 。ngx_shmtx_unlock 方 法 
在 释放 锁 时 也 会 用 到 sem_post 方 法 ， 如 下 所 示 。 


void ngx_shmtx_unlock(ngx_shmtx_t *mtx) 


// 释放 信号 量 锁 时 是 不 会 使 进程 睡眠 的 


if (sem post(&mtx->sem) == -1) { 
ngx_log_error(NGX_LOG ALERT, ngx_cycle->log, ngx_errno, 
"sem post() failed while wake shmtx"); 


在 14.8 中 我 们 将 会 讨论 Nginx 征 如 何 让 原子 变量 和 信和 号 量 合作 以 


实现 高 效 互 斤 锁 的 。 


14.7 文件 锁 


Linux 内 核 提 供 了 基于 文件 的 互 不 锁 ， 而 Nginx 框 架 封 狼 了 3 个 方 
法 ， 提 供给 Nginx 模 块 使 用 文件 互 斥 锁 来 保护 共 宇 数据 。 下 面 首 允 介 绍 
一 下 这 种 基于 文件 的 互 斤 锁 征 如 何 使 用 的 ， 其 实 很 简单 ， 通 过 fcnt 方 
法 就 可 以 实现 。 


int fcntJl(int fd, int cmd, struct flock *lock); 


这 个 方法 接收 3 个 参数 ， 其 中 参数 伺 是 打开 的 文件 句柄 ， 参 数 cmd 
表示 执行 的 锁 操作 ， 参 数 lock 措 述 了 这 个 锁 的 信息 。 下 面 依次 说 明 这 3 
个 参数 。 


参数 fq 必 须 生 已 经 成 功 打 开 的 文件 句柄 。 实 际 上 ，nginx.conf 文 件 
中 的 lock_file 配 置 项 指定 的 文件 路 径 ， 束 是 用 于 文件 互 斤 锁 的 ， 这 个 
文件 被 打开 后 得 到 的 句柄 ， 将 会 作为 fd 参数 传递 给 fcnt 方 法 ， 提 供 一 
种 锁 机 制 。 


这 里 的 cmd 参 数 在 Nginx 中 只 会 有 两 个 值 : FE_SETLK 和 
F_SEITLKW， 它 们 都 表示 试图 获得 互 斥 锁 ， 但 使 用 F_SETLK 时 如 果 互 
斥 锁 已 经 被 其 他 进程 占用 ，fcnt] 方 法 不 会 等 待 其 他 进程 释放 锁 且 自己 
拿 到 锁 后 才 返 回 ， 而 是 立即 返回 获取 互 斥 锁 失 败 ; 使 用 F_SETLKW 时 


则 不 同 ， 锁 被 占用 后 fcnt 方 法 会 一 直 等 待 ， 在 其 他 进程 没有 释放 锁 
时 ， 当 前 进程 殉 会 阻塞 在 fcnt 方 法 中 ， 这 种 阻塞 会 导致 当前 进程 由 可 
执行 状态 转 为 睡眠 状态 。 


参数 lock 的 类 型 是 flock 结 构 体 ， 它 有 5 个 成 员 是 需要 用 户 关 心 的 ， 
如 下 所 示 。 


struct flock 


// 锁 类 型 ， 取 值 为 
F_RDLCK、 
F_WRLCK 或 
F_UNLCK 


Short 1_type; 
// 锁 区 域 起 始 地 址 的 相对 位 


Short 1 whence; 
// 锁 区 域 起 始 地 址 偏 移 量 ， 同 


1_whence 共 同 确定 锁 区 域 


long 1_start; 
// 锁 的 长 度 ， 


0 表示 锁 至 文件 末 


long 1_len; 
// 拥有 锁 的 进程 


ID 
long 1 pid; ... 


}; 


从 flock 结 构 体 中 可 以 看 出 ， 文 件 锁 的 功能 绝 不 仅仅 局 限于 普通 的 
互 矿 锁 ， 它 还 可 以 锁 住 文件 中 的 部 分 内 容 。 但 Nginx 封 装 的 文件 锁 仅 用 
于 保护 代码 段 的 顺序 执行 〈 例 如 ， 在 进行 负载 均衡 时 ， 使 用 互 斥 锁 保 
证 同一 时 刻 仅 有 一 个 worker 进 程 可 以 处 理 新 的 TCP 连 接 ) ， 使 用 方式 
要 简单 得 多 : 一 个 lock_file 文 件 对 应 一 个 全 局 互 斥 锁 ， 而 且 它 对 master 
进程 或 者 worker 进 程 都 生效 。 因 此 ， 对 于 ]_start、1 len、1_ pid， 都 填 为 
0， 而 ]_whence 则 填 为 SEEK_SET， 只 需要 这 个 文件 提供 一 个 锁 。 
1_type 的 值 则 取决 于 用 户 是 想 实 现 阻 塞 睡 有 眠 锁 还 是 想 实现 非 阻 塞 不 会 睡 
眼 的 锁 。 


对 于 文件 锁 ，Nginx 封 装 了 3 个 方法 : ngx_trylock_fd 实 现 了 不 会 阻 
塞 进 程 、 不 会 使 得 进程 进入 睡 眼 状态 的 互 斥 锁 ;ngx_lock_fq 提 供 的 互 
斥 锁 在 锁 已 经 被 其 他 进程 拿 到 时 将 会 导致 当前 进程 进入 睡眠 状态 ， 直 
到 顺利 拿 到 这 个 锁 后 ， 当 前 进程 才 会 被 Linux 内 核 重 新 调度 ， 所 以 它 是 
阻塞 操作 ;ngx_unlock_fd 用 于 释放 互 斥 锁 。 下 面 我 们 一 一 列举 它们 的 
源 代码 。 


ngx_err_t ngx_trylock_fd(ngx_fd_t fd) 
{ 


struct flock fl， 
// 这 个 文件 锁 并 不 用 于 锁 文件 中 的 内 容 ， 填 充 为 


f1.1 start = 0; 
fl.1 len = 0; 
fl.1_ pid = 0; 

// F_SETLK 意 味 着 不 会 导致 进程 睡眠 


fl.1 type = F_WRLCK; 
fl.1 whence = SEEK_SET; 


// 获取 
fd 对 应 的 互 斥 锁 ， 如 果 ; 


- 工 ， 则 这 时 的 


人 
Gi 
荆 


ngx_errno 将 保存 错误 码 


if (fcnt1l(fd, F_SETLK, &f1) == -1) { 
return ngx_errnoy 


return 0) 


ww 


使 用 ngx_trylock_fd 方 法 获取 互 不 锁 成 功 时 会 返回 09， 否则 返回 的 
其 实 是 errno 错 误 码 ， 而 这 个 错误 码 为 NGX_EAGAIN 或 者 
NGX_EACCESS 时 表示 当前 没有 拿 到 互 斥 锁 ， 否 则 可 以 认为 fcnt 执 行 


ngx_lock_fd 方 法 将 会 阻塞 进程 的 执行 ， 使 用 时 需要 非常 刘 慎 ， 
可 能 会 导致 worker 进 程 宁可 睡眠 也 不 处 理 其 他 正常 请 求 ， 如 下 所 示 。 


x_err_t ngx_lock_fd(ngx_fd_t fd) 
{ 


Struct flock fl， 
fl.1 start = 0; 
fl.1 len = 
fl.1 pid = 

//F -8ETLKW 全 导 致 进程 睡 眼 


fl.1 type = F_WRLCK; 
fl.1 whence = SEEK_SET; 
// 如 果 返 区 


-14， 则 表示 


fcnt1 执 行 错误 。 返 蕊 


0， 表示 成 功 地 拿 到 了 锁 


if (fcntl(fd, F_SETLKW, &f1) == -1) { 
return ngx_errno,; 
} 


return ©; 


只 要 ngx_lock_fd 方 法 返回 9?， 就 表示 成 功 地 拿 到 了 互 不 锁 ， 否 则 
就 是 加 锁 操 作出 现 错误 。 


ngx_unlock_fd 方 法 用 于 释放 当前 进程 已 经 拿 到 的 互 斥 锁 ， 如 下 所 


尔 。 


ngx_err_t ngx_unlock_fd(ngx_fd_t fd) 


Struct flock fl， 

fl.1 start = 0; 

fl.1 len = 0; 

fl,.1 pid = 9; 

// F_UNLCK 表 示 将 要 释放 锁 


fl.1 type = F_UNLCK; 
fl.1 whence = SEEK_SET; 
// 返 世 


0 表示 成 功 


if (fcntl(fd, F_SETLK, &f1) == -1) { 
return ngx_errno,; 


return 09; 


当 关 闭 fd 句柄 对 应 的 文件 时 ， 当 前 进程 将 目 动 释放 已 经 拿 到 的 
Me 


14.8 互 斥 锁 


基于 原子 操作 、 信 和 号 量 以 及 文件 锁 ，Nginx 在 更 高 层次 封装 了 一 个 
互 斥 锁 ， 使 用 起 来 很 方便 ， 许 多 Nginx 模 块 也 是 更 多 直接 使 用 它 。 下 面 
看 一 下 表 14-1 中 介绍 的 操作 这 个 互 不 锁 的 5 种 方法 。 


表 14-1 互 不 锁 的 5 种 操作 方法 


方法 名 参 数 
参数 mtx 表示 待 操作 的 ngx_shmtx t 类 型 互 斥 锁 ; 
当 互 斥 锁 由 原子 变量 实现 时 ， 参 数 addr 表示 要 操作 
ngx shmtx create 的 原子 变量 锁 ， 而 互 斥 锁 由 文件 实现 时 ， 参 数 addr | 初始 化 mtx 互 斥 锁 
没有 任何 意义 ; 参数 name 仅 当 互 斥 锁 由 文件 实现 时 
才 有 意义 ， 它 表示 这 个 文件 所 在 的 路 径 及 文件 名 


让 
)C 


ngx_ shmtx destory 参数 mtx 表示 待 操作 的 ngx_shmtx_t 类 型 互 斥 锁 销毁 mtx 互 斥 锁 
无 阻塞 地 试图 获取 互 斥 锁 ， 返 回 
ngx_shmtx_trylock 参数 mtx 表示 待 操作 的 ngx_shmtx t 类 型 互 斥 锁 ”11 表示 获取 互 斥 锁 成 功 ， 返 回 0 表 


示 获 取 互 斥 锁 失 败 
以 阻塞 进程 的 方式 获取 互 斥 锁 ， 
在 方法 返回 时 就 已 经 持 有 互 斥 锁 了 


ngx shmtx unlock 参数 mtx 表示 待 操作 的 ngx_shmtx t 类 型 互 斥 锁 释放 互 斥 锁 


ngx_ shmtx lock 参数 mtx 表示 待 操作 的 ngx_shmtx_t 类 型 互 斥 锁 


表 14-1 中 的 5 种 方法 非常 全 面 ， 获 取 互 不 锁 时 既 可 以 使 用 不 会 阻塞 
进程 的 ngx_shmtx_trylock 方 法 ， 也 可 以 使 用 ngx_shmtx_lock 方 法 告诉 
Nginx 必 须 持 有 互 不 锁 后 才能 继续 向 下 执行 代码 。 它 们 都 通过 操作 
ngx_shmtx_t 类 型 的 结构 体 来 实现 互 不 操作 ， 下 面 再 来 看 一 下 
ngx_shmtx_t 中 有 了 哪些 成 员 ， 如 下 所 示 。 


typedef struct { 
#if (NGX_HAVE_ATOMIC_OPS ) 
// 原子 变量 锁 


ngx_atomic t *1ock 
#if (NGX_HAVE_POSIX_SEM ) 
// semaphore 为 


1 时 表示 获取 锁 将 可 能 使 用 到 的 信号 量 


ngx_uint_t semaphore,; 
// sem 就 是 信号 量 锁 


Sem t sem; 
#endif 
#else 

// 使 用 文件 锁 时 


fd 表示 使 用 的 文件 句柄 


ngx_fd t fd; 
ZI name 表示 文件 名 


u_char *name 
#endif 
/* 自 旋 次 数 ， 表 示 在 自 旋 状 态 下 等 待 其 他 处 理 器 执行 结果 中 释放 锁 的 时 间 。 由 文件 锁 实现 时 ， 


spin 没 有 任何 意义 


3 
ngx_uint_t spin; 
} ngx_shmtx_t; 


@@ 注音 谈 者 可 能 会 觉得 奇怪 ， 既 然 ngx_shmtx_t 结 构 体 中 的 spin 
成 员 对 于 文件 锁 没 有 任何 意义 ， 为 什么 不 放 在 
#if(NGX_HAVE_ATOMIC_OPS) 宏 内 呢 ? 这 是 因为 ， 对 于 使 用 
ngx_shmtx_t 互 斥 锁 的 代码 来 说 ， 它 们 并 不 想 知 道 互 斥 锁 是 由 文件 锁 、 
原子 变量 或 者 信号 量 实 现 的 。 同 时 ，spin 的 值 又 具备 非常 多 的 含义 (C 
语言 的 编程 风格 导致 可 读 性 比 面向 对 象 语言 差 些 ) ， 当 仅 用 原子 变量 
实现 互 斥 锁 时 ，spin 只 表示 自 旋 等 待 其 他 处 理 器 的 时 间 ， 达 到 spin 值 后 

就 会 “让 出 ”当前 处 理 器 。 如 有 果 spin 为 0 或 者 负 值 ， 则 不 会 存在 调用 

PAUSE 的 机 会 ， 而 是 直接 调用 sched_yield“ 让 出 ”处 理 器 。 假 设 同时 使 用 


信号 量 ，spin 会 多 一 种 含义 ， 即 当 spin 值 为 ngx_uint_t)-1 时 ， 相 当 于 告 
诉 这 个 互 斥 锁 绝 不 要 使 用 信号 量 使 得 进程 进入 睡眠 状态 。 这 点 很 重 
要 ， 实 际 上 ， 在 实现 第 9 章 提 到 的 负载 均衡 锁 时 ，spin 的 值 就 是 


(ngx_uint t)-—1° 


可 以 看 到 ，ngx_shmtx_t 结 构 体 涉及 两 个 安 : 
NGX_HAVE_ATOMIC OPS、NGX_HAVE _POSIX_ SEM， 这 两 个 宏 对 
应 着 互 斥 锁 的 3 种 不 同 实现 。 


第 1 种 实现 ， 当 不 文 持原 子 操作 时 ， 会 使 用 文件 锁 来 实现 
ngX_shmtx_t 互 斥 锁 ， 这 时 它 仅 有 fd 和 name 成 员 (实际 上 还 有 spin 成 
员 ， 但 这 时 没有 任何 意义 ) 。 这 两 个 成 员 使 用 14.7 市 介绍 的 文件 锁 来 提 
供 阻塞 、 非 阻塞 的 互 不 锁 。 


第 2 种 实现 ， 文 持原 子 操作 却 又 不 文 持 信 号 量 。 
第 3 种 实现 ， 在 支持 原子 操作 的 同时 ， 操 作 系 统 也 文 持 信 号 量 。 


后 两 种 实现 的 唯一 区 别 是 ngx_shmtx_lock 方 法 执行 时 的 效果 ， 也 就 
是 说 ， 文 持 信号 量 只 会 影响 阻塞 进程 的 ngx_shmtx_lock 方 法 持 有 锁 的 方 
式 。 当 不 支持 信号 量 时 ，ngx_shmtx_lock 取 锁 与 14.3.3 节 中 介绍 的 自 旋 
锁 是 一 致 的 ， 而 支持 信号 量 后 ，ngx_shmtx_lock 将 在 spin 指 定 的 一 段 时 
间 内 自 旋 等 待 其 他 处 理 器 释放 锁 ， 如 果 达 到 spin 上 限 还 没有 获取 到 锁 ， 
那么 将 会 使 用 sem_wait 使 得 当前 进程 进入 睡眠 状态 ， 等 其 他 进程 释放 了 


锁 内 核 后 才 会 唤醒 这 个 进程 。 当 然 ， 在 实际 实现 过 程 中 ，Nginx 做 了 非 
常 巧 妙 的 设计 ， 它 使 得 ngx_shmtx_lock 方 法 在 运行 一 段 时 间 后 ， 如 果 其 
他 进程 始终 不 放弃 钢 ， 那 么 当前 进程 将 有 可 能 强制 性 地 获得 到 这 把 

峰 ， 这 也 是 出 于 Nginx 不 宜 使 用 阻塞 进程 的 睡眠 锁 方 面 的 考虑 。 


14.8.1 文件 锁 实 现 的 ngx_shmtx_t 锁 


本 节 介 绍 如 何 通 过 文件 锁 实现 表 14-1 中 的 5 种 方法 〈 也 就 是 Nginx 对 
fcntl 系 统 调用 封装 过 的 ngx_trylock_fd、ngx_lock_fd 和 和 ngx_unlock_fd 方 
法 实现 的 锁 ) 。 


ngx_shmtx_create 方 法 用 来 初始 化 ngx_shmtx_t 互 不 锁 ，ngx_shmtx_t 
结构 体 要 在 调用 ngx_shmtx_create 方 法 前 先行 创建 。 下 面 看 一 下 该 方法 
的 源 代 码 。 


ngx_int_t ngx_shmtx_create(ngx_shmtx_t *mtx, void *addr, u_char *name) 


// 不 用 在 调 


ngx_shmtx_create 方 法 前 先行 赋值 给 


ngx_shmtx_t 结 构 体 中 的 成 员 


If (mtx->name) { 
/* 如 果 


ngx_shmtx_t 中 的 


name 成 员 有 值 ， 那 么 如 果 和 与 


name 参 数 相同 ， 意 味 着 


mtX 互 斥 锁 已 经 初始 化 过 了 ; 和 否则， 需要 移 销毁 


mtx 中 的 互 不 锁 再 重新 分 配 


mtx*/ 


If (ngx_strcmp(name, mtx->name) == 0) { 
// 如 果 
name 人 参数 与 


ngx_shmtx_t 中 的 


name 成 员 相 同 ， 则 表示 已 经 初始 化 了 


mtx->name = name; 
// 既然 曾经 初始 化 过 ， 证 


IO 


六 


fd 句柄 已 经 打开 过 ， 直 接 返回 成 功 即 可 


return NGX_0OK， 
/如 果 

ngx_shmtx_t 中 的 

name 与 参数 


name 不 一 致 ， 说 明 这 一 次 使 用 了 一 个 新 的 文件 作为 文件 锁 ， 那 么 先 调用 


ngx_shmtx_destory 方 法 销毁 原文 件 锁 


*/ 
ngx_shmtx_destory(mtx); 


} 
// 按照 
name 指 定 的 路 径 创 建 并 打开 这 个 文件 


mtx->fd = ngx_open_file(name，NGX_FILE_RDWR， NGX_FILE CREATE OR_OPEN, 
NGX_FILE_DEFAULT_ACCESS ) ， 

if (mtx->fd == NGX_INVALID_FILE) { 

// 文件 因为 各 种 原因 (如 权限 不 够 无 法 打开 ， 通 常会 出 现 无 法 运行 错误 


return NGX_ERROR; 


} 
/* 由 于 只 需要 这 个 文件 在 内 核 中 的 


INODE 信 息 ， 所 以 可 以 把 文件 删除 ， 只 要 


fd 可 用 就 行 


* 
/ 
if (ngx_delete file(name) == NGX_FILE ERROR) { 
} 


mtx->name = name; 
return NGX_OK， 


ngx_shmtx_create 方 法 需要 确保 ngx_shmtx_t 结 构 体 中 的 fd 是 可 用 
的 ， 它 的 成 功 执行 是 使 用 互 斥 锁 的 先决 条 件 。 


ngx_shmtx_destory 方 法 用 于 关闭 在 ngx_shmtx_create 方 法 中 已 经 打 
开 的 f 句 柄 ， 如 下 所 示 。 


void ngx_shmtx_destory(ngx_shmtx_t *mtx) 


// 关闭 


ngx_shmtx_t 结 构 体 中 的 


fd 句柄 


if (ngx_close file(mtx->fd) == NGX_FILE_ERROR) { 
ngx_1log_error(NGX_LOG ALERT, ngx_cycle->log, ngx_errno, 
ngx_close_file n " \"%s\" failed", mtx->name); 


ngx_shmtx_trylock 方 法 试图 使 用 非 阻 突 的 方式 获得 锁 ， 返 回 1 时 表 
示 获 取 锁 成 功 ， 返 回 0 表示 获取 锁 失败 。 


ngx_uint_t ngx_shmtx_trylock(ngx_shmtx_t *mtx) 


{ 


ngx_err_t err; 
// 由 


14.7 节 介绍 过 的 


ngx_trylock_fd 方 法 实现 非 阻 塞 互 不 锁 的 获取 


err = ngx_trylock_fd(mtx->fd); 
if (err == 0) { 
return 1; 


} 
// 如 果 


err 错 误 码 是 


NGX_EAGAIN， 则 表示 现在 锁 已 经 被 其 他 进程 持 有 了 


if (err == NGX_EAGAIN) { 


return 0， 
} 
ngx_log_abort(err, ngx_trylock fd _n " %s failed", mtx->name); 


return 0; 


ngx_shmtx_lock 方 法 将 会 在 获取 锁 失 败 时 阻塞 代码 的 继续 执行 ， 它 
会 使 当前 进程 处 于 睡眠 状态 ， 等 竺 其 他 进程 释放 锁 后 内 核 唤 醒 它 。 可 
见 ， 它 是 通过 14.7 节 介绍 的 ngx_lock_fd 方 法 实现 的 ， 如 下 所 示 。 


void ngx_shmtx_lock(ngx_shmtx_t *mtx) 


ngx_err_t err,; 
// ngx_lock_fd 方 法 返 区 


0 时 表示 成 功 地 持 有 锁 ， 返 世 


-1 时 表示 出 现 错 误 


err = ngx_lock_fd(mtx->fd); 
if (err == 0) { 
return; 


} 
ngx_log _ abort(err, ngx_lock_ fd _n " %s failed", mtx->name); 


ngx_shmtx_lock 方 法 没有 返回 值 ， 因 为 它 一 旦 返回 就 相当 于 获取 到 
互 斥 锁 了 ， 这 会 使 得 代码 继续 向 下 执行 。 
ngx_shmtx_unlock 方 法 通过 调用 ngx_unlock_fd 方 法 来 释放 文件 锁 ， 


如 下 所 示 。 


void ngx_shmtx_unlock(ngx_shmtx_t *mtx) 


ngx_err_t err; 
// 返 怕 


0 即 表 示 释 放 锁 成 功 


err = ngx_unlock_fd(mtx->fd); 


if (err == 0) { 
return; 


ngx_log_ abort(err, ngx_unlock_fd _n " %s failed", mtx->name); 


可 以 看 到 ，ngx_shmtx_t 互 斤 锁 在 使 用 文件 锁 实 现时 是 非常 简单 
的 ， 写 只 是 简单 地 封 攻 了 14.7 节 介绍 的 文件 锁 。 


14.8.2 ”原子 变量 实现 的 ngx_shmtx_t 铅 | 


当 Nginx 判 断 当 前 操作 系统 文 持原 子 变量 时 ， 将 会 优先 使 用 原子 变 
量 实现 表 14-1 中 的 5 种 方法 ( 即 原子 变量 锁 的 优先 级 高 于 文件 锁 ) 。 不 
过 ， 同 时 还 需要 判断 其 是 否 支 持 信 号 量 ， 因 为 支持 信号 量 后 进程 有 可 
能 进入 睡眠 状态 。 下 面 介绍 一 下 如 何 使 用 原子 变量 和 信和 号 量 来 实现 
ngx_shmtx_t 互 不 锁 ， 注 意 ， 它 比 文件 锁 的 实现 要 复杂 许多 。 


ngx_shmtx_t 结 构 中 的 lock 原 子 变 量 表示 当前 锁 的 状态 。 为 了 便于 
理解 ， 我 们 还 是 用 接近 自然 语言 的 方式 来 说 明 这 个 锁 ， 当 lock 值 为 0 或 
者 正 数 时 表示 没有 进程 持 有 锁 ， 当 lock 值 为 负数 时 表示 有 进程 正 持 有 锁 
(这 里 的 正 、 负 数 仅 相对 于 32 位 系统 下 有 符号 的 整 型 变量 ) 。Nginx 是 
怎样 快速 判断 lock 值 为 “ 正 数 ? 或 者 “负数 ”的 呢 ? 很 简单 ， 因 为 有 符号 整 
型 的 最 高 位 是 用 于 表示 符号 的 ， 其 中 0 表示 正 数 ，1 表 示 负 数 ， 所 以 ， 
在 确定 整 型 val 是 负数 或 者 正 数 时 ， 可 通过 判断 (val&0x80000000)==0 语 
句 的 真 假 进行 。 


下 面 看 一 下 初始 化 ngx_shmtx_ft 互 斥 锁 的 ngx_shmtx_create 方 法 究竟 
做 了 些 什么 事情 。 


ngx_int_t ngx_shmtx_create(ngx_shmtx_t *mtx, void *addr, u_char *name ) 


mtx->lock = addr; 
// 注意 ， 当 


spin 值 为 


-1 时 ， 表 示 不 能 使 用 信号 量 ， 这 时 直接 返回 成 功 


If (mtx->spin == (ngx_uint_t) -1) { 
return NGX_OK， 


} 
// ”spin 值 默认 为 
2048 


mtx->spin = 2048; 
// 同时 使 用 信和 号 量 


#if (NGX_HAVE_POSIX_SEM) 
// 以 多 进程 使 用 的 方式 初始 化 


sem 信 号 量 ， 
sem 初 始 值 为 


0 
if (sem init(&mtx->sem, 1, 0) == -1) { 
ngx_log_error(NGX_LOG ALERT, ngx_cycle->log, ngx_errno, 
"sem_init() failed"); 


} else { 
// 在 信号 量 初始 化 成 功 后 ， 设 置 
semaphore 标 志 位 为 
1 


mtx->semaphore = 1; 


#endif 
return NGX_OK， 
} 


spin 和 semaphore 成 员 都 将 决定 ngx_shmtx_lock 阻 塞 锁 的 行为 。 


ngx_shmtx_destory 方 法 的 唯一 目的 束 是 释放 信和 号 量 ， 如 下 所 示 。 


void ngx_shmtx_destory(ngx_shmtx_t *mtx) 


{ 
// 文 持 信号 量 时 才 有 代码 需要 执行 


#if (NGX_HAVE_ POSIX_SEM) 
A/* 当 这 把 锁 的 


spin 值 不 为 


(ngx_uint_t) -1 时 ， 且 初始 化 信号 量 成 功 ， 


semaphore 标 志 位 才 为 


1*/ 
if (mtx->semaphore) { 
// 销毁 信号 量 


if (sem destroy(&mtx->sem) == -1) { 
ngx_1log_error(NGX_LOG ALERT, ngx_cycle->log, ngx_errno, "sem destroy() 
failed"); 
} 
#endif 
} 


以 非 阻塞 方式 获取 锁 的 ngx_shmtx_trylock 方 法 较为 简单 ， 可 直接 判 
朵 lock 原 子 变量 的 值 ， 当 它 为 非 负数 时 ， 直 接 将 其 置 为 负数 即 表示 持 有 
锁 成 功 。 怎 样 把 0 或 者 正 数 置 为 负数 呢 ? 很 简单 ， 使 用 语句 
vall0x80000000 即 可 把 非 负数 的 val 变 为 负数 ， 这 种 方法 效率 最 高 ， 即 直 
接 修改 val 的 最 高 符号 标志 位 为 1。 


ngx_uint_t ngx_shmtx_trylock(ngx_shmtx_t *mtx) 


ngx_atomic uint_t val; 
// 取出 


lock 锁 的 值 ， 通 过 判断 它 是 否 为 非 负 数 来 确定 锁 状 态 


val = *mtx->lock; 
/* 如 果 


val 为 


0 或 者 正 数 ， 则 说 明 没 有 进程 持 有 锁 ， 这 时 调 


ngx_atomic_cmp_set 方 法 将 


1ock 锁 改 为 负数 ， 表 示 当 前 进程 持 有 了 互 斥 锁 


*/ 
return ((val & Ox80000000) == 0 && 
ngx_atomic_cmp_set(mtx->lock, val, val | 0x80000000 ) ) ， 


} 


@ 注意 (val&0x80000000)==0 是 一 行 语句 ， 而 
ngx_atomic_cmp_set(mtx->]lock,val,vall0x80000000) 叉 是 一 行 语句 ， 多 进 
程 的 Nginx 服 务 将 有 可 能 出 现 虽然 第 1 行 语句 执行 成 功 (表示 锁 未 被 任 
何 进 程 持 有 ) ， 但 在 执行 第 2 行 语句 前 ， 又 有 一 个 进程 拿 到 了 锁 ， 这 时 
第 2 行 语 句 将 会 执行 失败 。 这 正 是 ngx_atomic_cmp_set 方 法 目 身 先 判 断 
lock 值 是 否 为 非 人 负数 val 的 原因 ， 只 有 lock 值 为 非 负 数 val， 它 才 会 确定 
将 lock 值 赋 为 负数 vall0x80000000 并 返回 1， 否 则 返回 0 ( 详 见 14.3.2 


下) 


区 


O 〇 


阻塞 式 获取 互 斥 锁 的 ngx_shmtx_lock 方 法 较为 复杂 ， 在 不 支持 信和 号 
量 时 它 与 14.3.3 世 介绍 的 目 施 锁 几乎 完全 相同 ， 但 在 文 择 了 信和 号 量 后 ， 
它 将 有 可 能 使 进程 进入 睡眠 状态 。 下 面 我 们 分 析 一 下 它 的 操作 步 又 。 


void ngx_shmtx_lock(ngx_shmtx_t *mtx) 


ngx_uint_t i, n; 
ngx_atomic_uint_t val; 
// 没有 拿 到 锁 之 前 是 不 会 跳出 循环 的 


for ( ;; ) 
/*lock 值 是 当前 的 锁 状态 。 注 


中 


lock 一 般 是 在 共享 内 存 中 的 ， 它 可 能 会 时 刻 变化 ， 而 


代码 的 执行 中 它 可 能 与 


val 是 当前 进程 的 栈 中 变量 ， 下 面 


lock 值 不 一 致 


*/ 


val = *mtx->lock; 


/* 如 果 
val 为 非 负 数 ， 则 说 明 锁 未 被 持 有 。 下 面试 图 通过 修改 
lock 值 为 负数 来 持 有 锁 


*/ 
If ((val & Qx80000000) == 


&& Ngx_atomic cmp_set(mtx->lock, val, val | 0x80000000 ) ) 


/* 在 成 功 地 将 
lock 值 由 原先 的 


Val 改 为 非 负 数 后 ， 表 示 成 功 地 持 有 了 锁 ， 


ngx_shmtx_lock 方 法 结束 


*/ 
return; 


} 
// 仅 在 多 处 理 器 状态 下 
spin 值 才 有 意义 ， 否 则 


PAUSE 指 令 是 不 会 执行 的 


if (ngx_ncpu > 1) { 
// 循环 执行 


PAUSE， 检 查 锁 是 否 已 经 释放 


for (n= 1; n < mtx->spin,; n <<= 1) { 
// 随 着 长 时 间 没有 获得 到 锁 ， 将 会 执行 更 多 次 


PAUSE 才 会 检查 锁 
for (i = 0; i < n i++) 
// 对 于 多 处 理 器 系统 ， 执 行 


ngx_cpu_pause 可 以 降低 功 耗 


ngx_cpu_pause( ); 


} 
// 再 次 由 共享 内 存 中 获得 


lock 原 子 变量 的 值 


val = *mtx->lock; 
/* 检 查 


lock 是 否 已 经 为 非 负 数 ， 即 锁 是 否 已 经 被 释放 ， 如 果 锁 已 经 释放 ， 那 么 会 通过 


lock 原 子 变量 值 设置 为 负数 来 表示 当前 进程 持 有 了 锁 


*/ 


等 


if ((val & 0x80000000) == 
&& Ngx_atomic cmp_set(mtx->lock, val, val | 0x80000000 ) ) 


// 持 有 锁 成 功 后 立刻 返 


瑟 


return; 


} 
} 
// 文 持 信号 量 时 才 继 续 执行 


#if (NGX_HAVE_POSIX_SEM ) 
// semaphore 标 志 位 为 


1 才 使 用 信号 量 


if (mtx->semaphore) { 
// 重新 获取 一 次 可 能 在 共享 内 存 中 的 


lm 


lock 原 子 变量 


val = *mtx->lock; 


// 如 果 
lock 值 为 负数 ， 则 
lock 值 加 上 
1 
if ((val & Ox80000000) 


&& Ngx_atomic cmp_set(mtx->lock, val, val + 1)) 


/* 检 查 信 号 量 


sem 的 值 ， 如 果 
sem 值 为 正 数 ， 则 
sem 值 减 


| 


1， 表 示 拿 到 了 信号 量 互 不 锁 ， 同 时 


sem_wait 方 法 返 
0 。 如 果 
sem 值 为 
0 或 者 负数 ， 则 当前 进程 进入 睡眠 状态 ， 等 待 其 他 进程 使 用 


ngx_shmtx_unlock 方 法 释放 锁 (等 待 


sem 信 号 量变 为 正 数 ) ， 到 时 


Linux 内 核 会 重新 调度 当前 进程 ， 继 续 检 查 


sem 值 是 否 为 正 ， 


mh 


E 复 以 上 流程 


二 
while (sem wait(&mtx->sem) == -1) { 

ngx_err_t err; 

err = ngx_errno; 
// 当 


EINTR 信 和 号 出 现时 ， 表 示 


sem_wait 只 是 被 打 断 ， 并 不 是 出 错 


if (err != NGX_EINTR) { 
break; 


} 
} 
// 循环 检查 


lock 锁 的 值 ， 注 意 ， 当 使 用 信号 量 后 不 会 调用 


sched yield 
continue; 


#endif 
// 在 不 使 入 了 量 时 ， 调 


> 


sched_yie1d 将 会 使 当前 进程 暂时 * 让 出 ?处理 器 


ngx_Ssched_yield()， 


可 以 看 到 ， 在 不 使 用 信号 量 时 (例如 , NGX_HAVE_POSIX_SEM 
宏 没 打 开 ， 或 者 Spin 的 值 为 ngx_uint_D-1) ，ngx_shmtx_lock 方 法 与 
ngx_spinlock 方 法 非常 相似 ， 而 在 使 用 信号 量 后 将 会 使 用 可 能 让 进程 进 
入 睡眠 的 sem_wait 方 法 代替 “让 出 ”处 理 器 的 ngx_sched_yield 方 法 。 这 里 
不 建议 在 Nginx worker 进 程 中 使 用 带 信 号 量 的 ngx_shmtx_lock 取 锁 方 


湛 * 


ngx_shmtx_unlock 方 法 会 释放 鲍 ， 虽 然 这 个 释放 过 程 不 会 阻塞 进 
程 ， 但 设置 原子 变量 lock 值 时 是 可 能 失败 的 ， 因 为 多 进程 在 同时 修改 
lock 值 ， 而 ngx_atomic_cmp_set 方 法 要 求 参 数 old 的 值 与 lock 值 相同 时 才 


能 修改 成 功 ， 因 此 ，ngx_atomic_cmp_set 方 法 会 在 循环 中 反复 执行 ， 直 
到 返回 成 功 为 止 。 该 方法 的 实现 如 下 所 示 : 


void ngx_shmtx_unlock(ngx_shmtx_t *mtx ) 


{ 
ngx_atomic uint_t val, old, wait; 
// 试图 循环 重 置 


1ock 值 为 正 数 ， 此 时 务必 将 互 斥 锁 释 放 


(7; ) 区 
// 由 共享 内 存 中 的 


lock 原 子 变量 取出 锁 状 态 


old = *mtx->lock; 
// 通过 把 最 高 位 置 为 


0, 将 


lock 变 为 正 数 


wait = old & Ox7fffffff,; 
// 如 果 变 为 正 数 的 


lock 不 是 
0， 则 减 去 
1 
val = Wait wait - 1 : 0; 
// 将 
lock 锁 的 值 设 为 非 负 数 
val 
If (ngx_atomic cmp_set(mtx->lock, old, val)) { 


// 设置 锁 成 功 后 才能 跳出 循环 ， 否 则 将 持续 地 试图 修改 
lock 值 为 非 负数 


break; 


} 


} 
#if (NGX_HAVE POSIX_ SEM) 
/* 如 果 


lock 锁 原先 的 值 为 


909， 也 就 是 说 ， 并 没有 让 某 个 进程 持 有 锁 ， 这 时 直接 返回 ， 或 者 ， 


semaphore 标 志 位 为 


90， 表示 不 需要 使 用 信号 量 ， 也 立即 返 匠 


4 
if (wait == 0 || !mtx->semaphore) { 
return; 
} 


/* 通 过 


最 


sem_post 将 信和 号 


sem 加 


1， 表 示 当 前 进程 释放 了 信和 号 量 互 斥 锁 ， 通 知 其 他 进程 的 


sem_wait 继 续 执行 


*/ 
if (sem post(&mtx->sem) == -1) { 
ngx_1log_error(NGX_LOG ALERT, ngx_cycle->log, ngx_errno, 
"sem_post() failed while wake shmtx"); 


} 
#endif 
} 


由 于 原子 变量 实现 的 这 5 种 互 不 锁 方 法 是 Nginx 中 使 用 最 广泛 的 同 
步 方式 ， 当 需要 Nginx 文 持 数 以 万 计 的 并 发 TCP 请 求 时 ， 通 常 都 会 把 
spin 值 设 为 (ngx_uint_t)-1°。 这 时 的 互 不 锁 在 取 锁 时 都 会 采用 目 旋 锁 ， 对 
于 Nginx 这 种 单 进程 处 理 大 量 请 求 的 场景 来 说 是 非常 适合 的 ， 能 够 大 量 
降低 不 必要 的 进程 间 切 换 市 来 的 消耗 。 


所 刁 ”， 小 千 


Nginx 走 一 个 能 够 并 发 处 理 几 十 万 甚至 儿 百 万 个 TCP 连 接 的 高 性 能 
服务 器 ， 因 此 ， 在 进行 进程 间 通 信 时 ， 必 须 充分 考虑 到 不 能 过 分 影响 
正常 请 求 的 处 理 。 例 如 ， 使 用 14.4 节 介绍 的 套 接 字 通信 时 ， 套 接 字 都 
被 设 为 了 无 阻塞 模式 ， 防 止 执 行 时 阻塞 了 进程 导致 其 他 请 求 得 不 到 处 
理 ， 又 如 ，Nginx 封 洲 的 锁 都 不 会 直接 使 用 信号 量 ， 因 为 一 旦 获取 信和 与 
量 互 斤 锁 失 败 ， 进 程 殉 会 进入 睡眠 状态 ， 这 会 导致 其 他 请 求 " 场 死 ”。 


当 用 户 开 发 复杂 的 Nginx 模 块 时 ， 可 能 会 涉及 不 同 的 worker 进 程 间 
通信 ， 这 时 可 以 从 本 章 介绍 的 进程 间 通 信 方 式 上 进行 选择 ， 从 使 用 上 
说 ，ngx_shmtx_t 互 不 锁 和 共 译 内 存 应 当 是 第 三 方 Nginx 模 块 最 第 用 的 
进程 间 通 信 方 式 了 ，ngx_shmtx_t 互 不 锁 在 实现 中 充分 考虑 了 是 否 引 发 
睡眠 的 问题 ， 用 户 在 使 用 时 需要 明确 地 判断 出 是 否 会 引发 进程 睡眠 。 
当 然 ， 如 有 果 不 使 用 Nginx 封 逆 过 的 进程 间 通 信 方 式 ， 则 需要 注意 跨 平 


台 ， 以 及 十 否 会 阻塞 进程 的 运行 等 问题 。 


Nginx 有 许多 功能 体现 在 nginx.conf 这 个 脚本 式 的 配置 文件 里 ， 这 
些 配 置 项 的 格式 五 花 八 |]、 风 格 各 异 ， 原 因 是 它们 都 由 各 Nginx 模 块 目 
定义 ， 并 没有 什么 统一 的 标准 ， 这 在 第 4 章 已 经 提 及 。 然 而 ， 我 们 可 以 
看 到 许多 广 为 流 传 的 配置 项 ， 它 们 都 支持 在 一 行 配置 中 ， 加 入 诸如 $ 符 
号 紧 跟 字符 串 的 方式 ， 试 图 表达 实时 请 求 中 某 些 共性 参数 ， 就 像 编程 
语言 中 的 变量 与 值 ， 这 使 得 Nginx 的 使 用 成 本 、 学 习 成 本 大 幅 降低 ， 
Nginx 用 户 仅 在 nginx.conf 中 做 些 修改 丈 可 以 拥有 更 复杂 的 功能 


例如 在 指定 access.log 请 求 访问 日 志 格 式 的 时 候 ， 
ngx_http_log_module 模 块 束 介 许 Nginx 管 理 员 非常 灵活 地 定义 日 志 格 
式 ， 以 方便 诸如 awstats 等 第 三 方 统计 工具 能 够 依据 个 性 化 的 日 志 为 站 
长 们 分 析出 有 意义 的 结果 来 ， 例 如 : 


log_format main '$remote addr $remote user ' 
' [$time_local] "$request" $status ' 
'$host $body_bytes_sent $gzip_ratio "$http_referer" ' 
'"$http_user_agent" "$http_x_forwarded_ for"'; 
access_log logs/access.log main,; 


又 比如 ， 在 限制 用 户 的 请 求 访问 速度 时 ， 怎 样 判断 不 同 的 TCP 连 
接生 来 目 于 同一 用 户 的 请 求 呢 ? 有 些 场景 是 依据 TCP 连 接 的 对 端 IP， 
但 如 果 客 户 端 是 通过 代理 服务 右 访 问 则 又 不 可 靠 。 还 有 些 场景 会 依据 


http 头 部 的 cookie， 甚 至 更 小 众 的 需求 可 以 依据 URI 或 者 URL 参 数 。 
ngx_http_limit_req_module 模 块 提供 这 样 复杂 的 功能 以 满足 广泛 的 场 
景 ， 所 依据 的 也 是 在 nginx.conf 配 置 文件 中 提供 $ 这 样 的 配置 项 以 描述 
请 求 ， 比 如 可 以 依据 对 端 耻 进行 限 速 : 


limit_req_zone $binary_remote addr zone=one:10m rate=1r/s,; 


在 这 两 个 例子 中 ， 其 实 都 是 在 模块 中 使 用 Nginx 定 义 的 内 部 变量 ， 
像 $remote_addr 这 样 的 参数 。 这 些 内 部 变量 在 Nginx 官 方 代码 中 定义 ， 
目前 是 在 ngx_http_variables.c 文 件 的 ngx_http_core_variables 数 组 中 定义 
的 。 在 本 草 中 ， 我 们 首先 学 习 如 何在 目 己 的 模块 中 使 用 已 有 的 常用 内 
部 变量 ， 使 模块 具备 类 似 access_log 或 者 limit_req 模 块 在 nginx.conf 文 件 
中 配置 内 部 变量 的 功能 。 


除了 要 能 够 使 用 已 有 变量 外 ， 我 们 还 需要 具备 定义 新 的 内 部 变量 
的 能 力 ， 使 其 他 Nginx 模 块 也 能 够 使 用 我 们 定义 的 新 变量 。 这 些 新 变量 
与 现 有 的 内 部 变量 是 一 致 的 ， 也 是 在 使 用 到 的 时 候 开始 解析 、 缓 存 。 


官方 的 ngx_http_rewrite_module 模 块 还 提供 了 配置 文件 脚本 式 语法 


的 执行 ， 允 许 在 配置 文件 里 直接 定义 全 新 的 变量 ， 由 于 它 不 在 代码 中 
而 是 在 nginx.conf 中 定义 ， 所 以 称 其 为 外 部 变量 ， 例 如 : 


set $parameter1 "abcd"; 
set $memcached_key "$uri$args",; 


本 章 将 先 以 一 个 简洁 的 例子 摘 述 使 用 变量 的 基本 开发 方法 ， 再 通 
过 说 明 Nginx 对 变量 的 实现 原理 使 读者 更 透彻 地 理解 这 种 开发 方式 ， 进 
而 再 扩展 这 个 例子 ， 帮 助 读者 更 灵活 地 掌握 变量 的 使 用 。 最 后 ， 则 会 
以 一 个 位 单 的 外 部 变量 配置 为 例 ， 介 绍 脚 本 引擎 是 怎样 编译 、 执 行 脚 
本 指令 的 。 


15.1 使 用 内 部 变量 开发 模块 


使 用 Nginx 预 定义 的 内 部 变量 的 方法 非常 向 单 ， 将 你 需要 使 用 的 变 
量 名 作为 参数 传 入 〈 例 如 在 解析 配置 文件 的 时 候 ) ， 调 用 
ngx_http_get_variable_index 方 法 ， 获 取 到 这 个 变量 名 对 应 的 索引 值 ， 
如 下 : 


nh gt warie Me con tSoty i sot oan 

字符 串 ngx_str_t 类 型 的 name 束 是 变量 名 ， 这 个 变量 名 必须 是 茶 个 
Nginx 模 块 定义 过 的 ， 返 回 值 束 是 这 个 变量 的 索引 值 。 关 于 变量 的 索引 
在 15.2 玫 再 详细 说 明 ， 通 彰 来 说 ， 使 用 索引 值 而 不 是 变量 字符 串 来 获 
取 变 量 值 是 个 好 主意 ， 它 会 加 快 Nginx 的 执行 速度 。 事 实 上 ，Nginx 提 
供 了 两 种 方式 来 找 出 要 使 用 的 内 部 变量 ， 一 种 是 索引 过 的 变量 ， 可 直 
接 由 数组 下 标 找到 元 素 ， 男 一 种 是 添加 到 散 列 表 的 变量 ， 需 要 将 字符 
串 变 量 名 由 散 列 方法 算出 散 列 值 ， 再 从 散 列 表 中 找 出 元 隶 ， 遇 到 元 又 
冲突 时 需要 遍历 开 散 列表 的 横 位 链表 (参见 第 7 章 ) 。 可 见 ， 哪 个 更 快 
古 一 目 了 然 的 ， 当 然 ， 索引 变量 要 比 散 列 变 量 占 用 多 一 点 的 内 存 。 


保存 这 个 索引 值 (例如 在 你 的 配置 结构 体 中 ) 。 处 理 请 求 时 ， 则 
使 用 这 个 索引 值 ， 调 用 ngx_http_get_indexed_variable 方 法 获取 到 变量 


的 值 ， 如 下 : 


ngx_http_variable value 七 * 
ngx_http_get_indexed variable(ngx_http_request_t *r, ngx_uint_t index) 
index 参 数 就 是 ngx_http_get_variable_index 方 法 获得 的 变量 索引 ， 
而 I 参数 当然 束 是 请 求 了 ， 每 一 个 变量 的 值 都 随 大 请 求 的 不 同 而 变化 。 
方法 的 返回 值 就 是 变量 值 ， 当 然 返 回 NULL 即 没有 解析 出 变量 。 


最 基本 的 使 用 变量 方法 束 是 如 此 人 简单， 我 们 先 不 探究 更 灵活 的 使 
用 方式 和 数据 成 员 的 详细 意义 ， 先 以 一 个 可 运行 的 例子 来 给 不 熟悉 的 
读者 朋友 一 个 直观 的 认识 。 


在 配置 文件 中 使 用 变量 可 以 提高 模块 功能 的 灵活 性 ， 也 是 Nginx 模 
块 的 常用 手法 。 就 如 第 4 章 所 述 ，nginx.conf 中 的 配置 项 格式 如 何 设计 
完全 是 模块 的 自由 ， 即 使 把 配置 项 设计 得 无 比 男 类 也 不 影响 我 们 使 用 
内 部 变量 。 然 而 ， 符 合 惯例 的 设计 会 降低 使 用 、 维 护 成 本 ， 因 此 ， 最 
好 还 是 在 配置 文件 中 使 用 变量 时 在 变量 名 前 加 上 “$” 符 号 。 本 节 的 这 个 
例子 将 实现 以 下 功能 : 在 配置 文件 中 指定 某 些 location 下 的 请 求 来 临 
时 ， 必 须根 据 配置 项 myallow 指 定 的 变量 及 其 判定 值 来 决定 请 求 是 否 被 
允许 。 比 如， 如 果 在 nginx.conf 中 加 入 下 面 这 段 配 置 ， 这 个 模块 束 会 通 
过 myallow 选 项 决定 某 些 请 求 必 须 具 备 testHeader:xxx 这 样 的 http 头 部 才 
能 放行 ， 有 些 请 求 则 必须 来 自 于 IP 10.69.50.199 才 能 放行 ， 只 要 是 
Nginx 定 义 的 内 部 变量 都 可 以 放 在 myallow 中 。 


location /test1 { 
myallow $http_testHeader xxx; 
root /www/test1; 


} 
location /test2 { 
root /www/test2; 


location / { 

root /Www; 

myallow $remote addr 10.69.50.199; 
} 


当 location 内 的 请 求 到 达 时 ，myallow 配 置 将 会 在 
NGX_HTTP_ACCESS_PHASE 阶 段 产 生 作 用 ， 当 有 具备 相应 的 如 
$varaible 内 部 变量 ， 且 其 值 为 myallow 的 第 2 个 参数 时 ， 这 个 请 求 才能 
继续 进行 ， 否 则 返回 403 错 误 码 。 


笔者 构造 这 个 例子 虽然 试图 简单 到 只 使 用 http 内 部 变量 ， 却 仍然 
使 用 到 了 第 4 章 的 配置 项 解析 、 第 11 章 的 HITP 访 问 控制 阶段 ， 读 者 阅 
读 时 知 有 疑问 可 翻阅 这 两 章 回 顾 。 


15.1.1 定义 模块 


这 次 把 模块 名 取 为 ngx_http_testvariable_module， 通 过 config 配 置 
文件 把 模块 编译 进 Nginx 的 方法 参见 第 3 章 ， 这 一 小节 仅 定 义 表示 模块 
的 数据 结构 ， 如 下 : 


ngx_module t ngx_http_testvariable module = 


NGX_MODULE_V1, 

&ngx_http_testvariable module_ ctx, 
ngx_http_testvariable_commands, 

NGX_HTTP_MODULE， /* module type */ 


NULL, /* init master */ 


NULL, /* init module */ 
NULL， /* init process */ 
NULL, /* init thread */ 
NULL, /* exit thread */ 
NULL， /* exit process */ 
NULL, /* exit master */ 


AGODutE V4._PADDING 

这 个 模块 是 一 个 普通 http 模 块 ， 所 以 不 需要 在 通用 的 master 、 
worker 进 程 启动 过 程 中 引入 回调 方法 ， 而 是 在 
ngx_http_testvariable_module_ctx 中 决定 了 在 http{} 配 置 解析 时 的 调用 方 
式 ，15.1.2 玫 会 描述 这 一 结构 体 的 定义 。 
ngx_http_testvariable_commands 描 述 了 模块 如 何 解析 配置 项 ， 在 15.1.3 
节 会 详细 描述 。 


15.1.2 ”定义 http 模 块 加 载 方式 


ngx_http_testvariable_module_ctx 的 定义 如 下 : 


static ngx_http_module t ngx_http_testvariable module ctx = 


// 不 需要 在 解析 配置 项 前 做 些 什 么 。 如 果 需 要 添加 新 变量 ， 则 必须 在 这 个 回调 方法 中 实现 


NULL， /* preconfiguration */ 
// 解析 配置 完毕 后 会 回调 


ngx_http_mytest_init 
ngx_http_mytest_init, /* postconfiguration */ 
// myallow 配 置 不 能 存在 于 


http{} 和 


server{} 配 置 下 ， 所 以 通常 下 面 


4 个 回调 方法 不 用 实现 


BE 


NULL， /* create main configuration */ 


NULL， /* init main configuration */ 


NULL， /* create Server configuration */ 
NULL， /* merge server configuration */ 
// 生成 存放 
Location 下 
myallow 配 置 的 结构 体 
ngx_http_mytest_create_ loc_conf, /* create location configuration */ 


// 因为 不 存在 合并 不 同 级 别 下 冲突 的 配置 项 的 需求 ， 所 以 不 需要 


merge 方 法 


NULL /* merge location configuration */ 


}; 


这 个 定义 表明 ，http 配 置 项 解析 完毕 后 需要 调用 
ngx_http_mytest_init 方 法 ， 因 为 在 这 个 方法 中 ， 我 们 将 会 把 
ngx_http_testvariable_module 模 块 加 入 到 请 求 的 处 理 流程 中 ;而 
ngx_http_mytest_create_loc_conf 回 调 方法 负责 生成 存储 配置 的 
ngx_myallow_loc_conf t 结 构 体 : 


typedef Struct { 
// 变量 


variable 的 索引 值 


int variable_index; 
// myallow 配 置 后 第 


1 个 参数 ， 表 示 待 处 理 变量 名 


ngx_str_t variable,; 
// myallow 配 置 后 第 


2 个 参数 ， 表 示 变 量 值 必须 为 


equalvalue 才 能 放行 请 求 


ngx_str_t equalvalue,; 
} ngx_myallow_loc conf_t; 


ngx_http_mytest_create_loc_conf 方 法 只 是 负责 在 每 个 location 下 生 
成 ngx_myallow_loc_conf t 结 构 体 ， 所 以 一 如 既往 的 人 简单 : 


static void * 
ngx_http_mytest_create_ loc conf(ngx_conf_t *cf) 


ngx_myallow_loc conf_t *conf,; 
conf = ngx_pcalloc(cf->pool, sizeof(ngx_myallow_loc_conf_t)); 
if (conf == NULL) { 

return NULL; 


} 
// 没有 出 现 


myallow 了 配置 时 


variable_index 成 员 为 
-1 


conf->variable_index = -1; 
return conf; 


ngx_http_mytest_init 方 法 用 来 把 处 理 请 求 的 方法 
ngx_http_mytest_handler 加 入 到 Nginx 的 11 个 HTTP 处 理 阶 段 中 ， 由 于 我 
们 是 需要 控制 请 求 的 访问 权限 ， 因 此 会 把 它 加 入 到 
NGX_HTTP_ACCESS_PHASE 阶 段 中 ， 如 下 : 


static ngx_int_t 
ngx_http_mytest_init(ngx_conf_t *cf) 


ngx_http_handler_pt *h; 
ngx_http_core main conf_t *cmcf; 
// 取出 全 局 唯一 的 核心 结构 体 


ngx_http_core_main_conf_t 
cmcf = ngx_http_conf_get module main conf(cf, ngx_http_core module); 


// 在 


cmcf->phases[NGX_HTTP_ACCESS_PHASE] 阶 段 添 加 处 理 方法 


h = ngx_array_push(&cmcf->phases[NGX_HTTP_ACCESS_PHASE] ,handlers ) ; 
if (h == NULL) { 

return NGX_ERROR ， 
} 


// 处 理 请 求 的 方法 是 本 模块 的 


ngx_http_mytest_handler 方 法 


*h = ngx_http_mytest_handler; 
return NGX_OK; 


15.1.3 ”解析 配置 中 的 变量 


解析 配置 项 的 ngx_http_testvariable_commands 数 组 定义 如 下 : 


static ngx_command t ngx_http_testvariable commands[] = 


{ 
ngx_string("myallow"), 
// 配 项 只 能 存在 于 
location 内 ， 且 只 能 有 
2 个 参数 
NGX_HTTP_LOC_CONF | NGX_CONF_TAKE2, 
ngx_http_myallow, 
NGX_HTTP_LOC_CONF_OFFSET, 
09, 
NULL 
}, 


ngx_null command 


}; 


解析 myallow 配 置 项 时 完全 没有 使 用 预 置 的 解析 方法 ， 全 靠 新 定义 
的 ngx_http_myallow 方 法 。 由 于 我 们 把 配置 项 定义 为 : 


myallow $remote addr 10.69.50.199; 


所 以 ， 解 析 时 第 1 个 参数 需要 确认 第 1 个 字符 必须 是 以 “$” 符 号 开 


始 ， 之 后 的 字符 串 必 须 是 一 个 已 经 定义 的 变量 ， 第 2 个 参数 则 做 普通 字 


从 串 处 理 ， 如 下 : 


static char * 
ngx_http_myallow(ngx_conf_t * cf, ngx_command t * cmd, void * conf) 


ngx_str_t *value,; 
ngx_myallow_loc_conf_t *macf = conf; 
value = cf->args->elts,; 
// myallow 只 会 有 


2 个 参数 ， 加 上 其 自身 ， 


cf->args 应 


3 个 成 员 


if (cf->args->nelts != 3) { 
return NGX_CONF_ERROR ， 


1 个 参数 必须 是 


Ud 


$ 打 头 的 字符 有 


if (value[1].data[0] == '$') { 
// 去 除 第 


1 个 

$ 字 符 后 ， 

value[1] 就 是 变量 名 
value[1].1len--; 
value[1].datat+; 
// 获取 变量 名 在 


Nginx 中 的 索引 值 ， 加 速 访问 


macf->variable_ index = ngx_http_get_ variable index(cf, &value[1]); 
If (macf->variable_ index == NGX_ERROR) { 
return NGX_CONF_ERROR ， 


} 
macf->variable = value[1]; 
} else { 
return NGX_CONF_ERROR ， 
} 
// 保存 
myallow 的 第 


2 个 参数 


macf->equalvalue= value[2]; 
return NGX_CONF_OK ， 
} 


这 样 ， 每 个 location 下 都 有 的 ngx_myallow_loc_conf t 结 构 体 就 存放 
了 可 能 存在 的 这 两 个 参数 ， 留 竺 处 理 请 求 时 使 用 。 


15.1.4 ”处 理 请 求 


ngx_http_mytest_init 方 法 已 经 决定 http 请 求 到 达 Nginx 后 ， 将 会 在 
NGX_HTTP_ACCESS_PHASE 阶 段 按照 模块 顺序 调用 到 这 个 自 定义 的 
ngx_http_mytest_handler 方 法 。 在 这 个 方法 中 ， 我 们 首先 需要 取出 请 求 
选用 的 location 下 的 ngx_myallow_loc_conf t 结 构 体 ， 它 表明 了 location 
下 是 否 具 有 myallow 配 置 项 一 一 这 由 variable_index 是 否 为 -1 决定 。 接 
着 ， 调 用 ngx_http_get_indexed_variable 方 法 取出 做 了 索引 的 变量 ， 再 
比较 变量 的 值 是 否 邱 equalvalue 字 符 串 完全 相同 ， 大 相同 则 权限 判断 阶 
段 通 过 ， 人 否则 返回 403 拒 绝 请 求 。 方 法 实现 如 下 : 


static ngx_int_t ngx_http_mytest_handler(ngx_http_request _t *r) 
{ 


ngx_myallow_loc conf_t *conf,; 
ngx_http_variable_ value _t *VV; 
// 先 取 到 当前 


location 下 本 模块 的 配置 项 存储 结构 体 


conf = ngx_http_get_ module_ loc_ conf(r, ngx_http_testvariable_ module); 
if (conf == NULL) { 
return NGX_ERROR ， 


} 
// 如 果 


location 下 没有 


myallow 配 置 项 ， 放 行 请 求 


if (conf->variable index == -1) { 
return NGX_DECLINED,; 


} 
// 根据 索引 过 的 


variable_index 下 标 ， 快 速 取得 变量 值 


VV 
vv = ngx_http_get_indexed_variable(r, conf->variable_index); 
If (vv == NULL || vv->not_found) 区 
return NGX_HTTP_FORBIDDEN ， 


} 
// 比较 变量 值 是 否 与 


conf->equalvalue 相 同 ， 完 全 相同 才 会 放行 请 求 


if (vv->len == conf->equalvalue.len && 
© == ngx_strncmp(conf->equalvalue.data,vv->data,vv->len)) { 
return NGX_DECLINED, 


} 
// 否则 ， 返回 


403 拒 绝 请 求 继续 向 下 执行 


return NGX_HTTP_FORBIDDEN; 


如 此 ， 这 个 简单 的 模块 惑 开发 完成 了 。 这 个 例子 很 简单 ， 仅 用 于 
快速 上 手 ， 使 用 变量 的 更 多 功能 前 我 们 必须 移 理 清 变量 工作 的 原理 。 


15.2 ”内 部 变量 工作 原理 


理解 内 部 变量 的 设计 要 从 其 应 用 场景 入 手 。 顾 名 思 义 ，“ 内 部 ” 变 
量 是 在 Nginx 的 代码 内 部 定义 的 ， 也 就 古 说 ， 它 古 由 Nginx 模 块 在 C 代 码 
中 定义 的 。 读 者 对 C 语 言 应 该 是 比较 熟悉 的 ， 变 量 通 党 有 “声明 ”、“ 定 
义 ”、“ 赂 值 ”、“ 使 用 ”这 4 个 阶段 ， 而 上 面 所 说 的 定义 ， 实 际 上 更 像 古 C 
语言 里 的 声明 ， 为 什么 呢 ? 因为 现在 只 是 说 明 有 这 人 么 一 个 变量 ， 而 没 
有 实际 分 配 用 于 存储 变量 值 的 内 存 。 什 么 时 候 分 配 存 储 变 量 值 的 内 存 
空间 呢 ? 只 有 对 变量 风 值 的 时 候 ! 这 有 两 个 原因 ， 一 是 变量 值 的 大 小 
古 不 确定 的 ， 提 前 分 配 会 导致 内 存 浪 费 或 者 不 必要 的 内 存 拷贝 ， 二 是 
一 个 变量 可 能 在 很 多 场景 的 请 求 中 是 得 不 到 使 用 的 ， 提 前 分 配 是 不 必 
要 的 。 接 着 ，Nginx 框 架 会 从 性 能 的 角度 考虑 ， 将 所 有 内 部 变量 生成 散 
列表 ， 同 时 也 允许 各 个 模块 将 它们 各 目 需 要 的 变量 索引 到 一 个 数组 
中 ， 加 快 访问 速度 。 


在 请 求 到 来 时 ，Nginx 对 变量 的 赋值 通常 是 采取 “用 时 赋值 ”的 策 
上 略 ， 也 就 是 说 ， 只 有 当 某 个 模块 试图 取 变 量 的 值 时 才 会 对 变量 进行 赋 
值 ， 而 不 古 接收 了 完整 的 HTTP 头 部 后 束 开 始 解 析 变 量 。 当 然 ， 后 者 这 
种 提前 赋值 更 符合 直观 理解 ， 但 是 绝 大 部 分 变量 就 是 这 么 设计 的 ， 为 
什么 呢 ? 因为 Nginx 有 是 一 个 极度 追求 性 能 、 应 用 场景 单一 的 平台 ， 它 主 
要 用 于 Web 前 端 ， 许 多 Nginx 模 块 各 目 负 责 痢 不 同 的 请 求 ， 因 此 ， 对 于 


每 个 请 求 都 去 解析 一 过 所 有 的 变量 ， 这 个 代价 束 有 些 大 了 ， 反 而 是 对 
于 一 个 请 求 而 言 ， 首 次 使 用 一 个 变量 时 才 去 解析 、 给 它 赋 值 、 缓 存 变 
量 值 ， 之 后 就 直 接 取 绥 存 值 ， 这 种 方式 性 能 高 得 多 ， 有 所 像 Linux 进 程 
fork 时 的 “copy on write"， 原 因 都 是 一 个 请 求 多 半 只 使 用 全 部 变量 的 一 


小 部 分 。 


使 用 变量 时 ，Nginx 提 供 了 两 种 方式 找到 变量 :一 是 根据 索引 值 直 
接 找 到 数组 里 的 相应 要 量 ; 二 是 根据 变量 名 字符 串 hash 出 的 散 列 值 ， 依 
据 散 列表 找到 相应 的 变量 。 没 有 第 3 种 方式 ， 因 此 ， 如 果 我 们 定义 了 一 
个 变量 ， 但 设 定 为 不 能 hash 进 入 散 列 表 ， 同 时 ， 使 用 该 变量 的 模块 又 没 
有 把 它 加 入 索引 数组 ， 那 么 这 个 变量 是 无 法 使 用 的 。 


15.2.1 何 时 定义 变量 


开发 Nginx 模 块 时 ， 什 么 时 候 、 在 哪个 回调 方法 里 定义 变量 呢 ? 这 
当然 不 是 随意 的 ， 因 为 变量 的 赋值 等 许多 工作 都 是 由 Nginx 框 架 来 做 
的 ， 所 以 Nginx 的 HTTP 框 架 要 求 : 所 有 的 HTTP 模 块 都 必须 在 
ngx_http_module_t 结 构 体 中 的 preconfiguration 回 调 方法 中 定义 新 的 变 
量 。 为 什么 要 在 这 里 定义 变量 呢 ? 我 们 回顾 第 10 章 HTTP 框 架 的 初始 化 
流程 ， 图 10-10 为 了 使 主流 程 更 清晰 忽略 了 变量 的 处 理 ， 我 们 从 图 10-10 
中 第 3 步 创 建 配置 结构 体 开 始 ， 给 出 变量 的 初始 化 流程 图 ， 如 图 15-1 所 


修 ° 


简单 解释 网 15-1 里 各 个 步 又 与 变量 间 的 关系 : 


1) 调用 各 HTTP 模 块 的 create_(main/src/loc)_conf 方 法 ， 用 于 第 3 步 
解析 配置 项 时 存放 配置 参数 。 也 得 有 个 地 方 存放 配置 文件 中 的 变量 名 
或 者 索引 ! 


2) 按照 所 有 HTTP 模 块 的 顺序 ， 调 用 它们 的 preconfiguration 方 法 
(如 果实 现 的 话 ) 。 要 想 定义 变量 ， 这 是 唯一 的 机 会 。 


1 ) 调用 各 HTTP 模 块 的 create_(main/sre/loc)_conf 方 法 用 于 存放 解析 出 的 配置 项 


2 ) 调用 各 HTTP 模 块 的 preconfiguration 方 法 ， 可 引入 新 变量 


2.1 ) ngx_http_core_module 模 块 在 这 一 步 中 添加 ngx_http_core_variables 核 心 变量 


2.2 ) 其 他 模块 依次 在 preconfiguration 方 法 中 可 能 加 入 新 的 变量 


3 ) 开始 解析 、 处 理 http{..j 块 下 的 所 有 配置 项 


3.1 ) 各 模块 解析 配置 的 方法 中 ， 可 能 会 将 某 个 变量 索引 化 


4) 依次 调用 HTTP 模 块 的 postconfiguration 方 法 使 模块 介入 HTTP 处 理 阶段 中 


SD) 调用 ngx_http_variables_init_vars 方 法 初始 化 所 有 变量 


5.1 ) 检查 索引 变量 的 合法 性 ， 并 设置 其 解析 方法 


5.2 ) 初始 化 索引 过 的 http_、sent_http_、upstream_http_、cookie_、arg_ 变 量 


5.3 ) 将 需要 散 列 的 变量 构造 出 静态 散 列 表 


ba 


图 15-1 HTTP 变 量 的 初始 化 


2.1) HTTP 模 块 中 ，ngx_http_core_module 模 块 是 排名 第 1 的 ， 所 以 
会 首先 执行 它 的 preconfiguration 方 法 (实际 为 


ngx_http_core_preconfiguration 方 法 ) : 


static ngx_http_module t ngx_http_core module ctx = { 
ngx_http_core_preconfiguration, /* preconfiguration */ 


}; 


而 这 个 方法 中 其 实 殴 干 了 一 件 事 : 调用 
ngx_http_variables_add_core_vars 方 法 ， 把 用 于 存放 变量 的 结构 体 初 始 
化 ， 再 将 Nginx 核 心 变 量 加 入 谁 备 hash 的 数组 variables_keys 中 。 核 心 变 
量 可 以 在 
http://nginx.org/cn/docs/http/ngx_http_core_module.html#variables 页 面 中 
查看 ， 这 里 不 再 重复 。 


在 15.1 市 的 例子 中 我 们 使 用 的 变量 $remote_addr 实 际 上 就 是 
ngx_http_core_module 模 块 定义 的 ， 它 通过 ngx_http_core_variables 数 组 
有 这 么 一 行 定 义 代码 : 

static ngx_http_variable t ngx_http_core variables[] = { 


{ ngx_string("remote addr"), NULL, 
ngx_http_variable_remote addr, 0, 0, 0 }, 


} 


ngx_http_variables_add_core_vars 方 法 会 将 ngx_http_core_variables 数 


组 里 的 所 有 核心 变量 添加 到 Nginx 框 架 中 。 下 一 市 我 们 再 谈 这 个 过 程 古 


蚊 样 进行 的 。 


2.2) 在 2.1 步 之 后 ， 其 他 HTTP 模 块 才 可 以 在 各 自 的 preconfiguration 
方法 中 加 入 自 定义 的 内 部 变量 ，15.3 节 中 有 一 个 简单 的 例子 。 


3) 解析 配置 文件 http{} 块 中 的 配置 项 ， 根 据 配 置 项 名 称 找 到 其 对 
应 模块 的 ngx_command_t 结 构 体 ， 根 据 解 术 方 法 来 处 理 配置 项 。 


3.1) 需要 使 用 变量 的 模块 ， 通 常会 在 解析 配置 的 这 一 步 中 将 待 使 
用 的 变量 索引 化 。 为 什么 呢 ? 因 为 变量 索引 化 是 有 代价 的 ， 所 有 索引 
化 的 变量 部 会 导致 存储 请 求 的 结构 体 ngx_http_request_t 增 加 内 存 占 用 。 
而 索引 化 又 是 有 好 处 的 ， 它 的 算法 复杂 度 是 DO(1)， 而 使 用 散 列 表 则 移 
需要 hash 出 散 列 值 ， 再 需要 处理 散 列 桶 冲突 后 的 链表 授 历 问题 。 那 么 ， 
是 否 索引 变量 就 与 server、location 配 置 相关 了 ， 所 以 只 有 确定 会 用 到 变 
量 的 请 求 才 进行 案 引 ， 这 样 通常 部 把 是 否 使 用 变量 交 给 配置 项 决定 。 


4) 调用 各 HTTP 模 块 的 postconfiguration 方 法 。 这 时 解析 完 配 置 
了 ， 初 始 化 完 变 量 了 ， 这 里 会 决定 模块 怎样 介入 到 HTTP 请 求 的 处 理 
中 o 
5) 调用 ngx_http_variables_init_vars 方 法 初始 化 HTTP 变 量 。 这 一 方 


法 主要 包括 3 个 子 步 又 。 


5.1) 一 个 变量 是 否 进行 索引 ， 应 该 由 使 用 它 的 模块 决定 ， 而 不 是 
由 定义 它 的 模块 决定 。 这 样 束 可 能 市 来 冲突 ， 如 果 使 用 模块 索引 了 一 
个 变量 ， 其 实 却 没有 其 他 模块 定义 它 怎 么 办 ? 或 者 说 ， 有 模块 定义 了 
它 ， 但 是 这 个 模块 没有 编译 进 Nginx 怎 么 办 ? 所 以 ， 
ngx_http_variables_init_vars 方 法 首先 要 确保 索引 了 的 要 量 都 是 合法 的 : 
索引 过 的 变量 必须 是 定义 过 的 ; 其 次 ， 使 用 索引 要 量 的 模块 只 知道 索 
引 某 个 变量 名 ， 此 时 需要 把 相应 的 变量 值 解析 方法 等 属性 也 设置 好 。 


5.2) 通常 变量 名 是 非常 明确 的 ， 可 以 在 C 代 码 中 定义 变量 时 用 hard 
code 的 方式 编写 变量 名 ， 然 而 还 有 一 些 变 量具 有 两 个 特点 : 它们 的 名 
称 是 未 知 的 ， 但 是 如 何 解析 它们 却 是 一 目 了 然 的 。 例 如 ，HTTP 的 URL 
中 的 变量 ， 就 像 请 求 /sitemap.xmlpage_num=2 里 的 page_num， 如 何 解 析 
它 是 非常 明确 的 ， 怠 是 在 HTTP 请 求 行 ? 符号 后 的 参数 中 按 规则 解析 出 
page_num 即 可 。 这 样 的 参数 五 花 八 门 ， 什 么 样 的 都 有 ， 解 析 方 法 实际 
只 有 一 个 : 根据 变量 名 在 一 段 字符 串 中 找到 即 可 。 这 样 的 请 求 Nginx 总 
结 为 5 类 ， 它 们 仅 需 要 5 个 固定 的 解析 变量 方法 即 可 ， 而 每 类 中 的 变量 
名 是 不 确定 的 ， 由 使 用 变量 的 模块 决定 。 这 5 类 变量 都 由 HTTP 框 架 定 
义 ， 而 要 求 使 用 它们 的 模块 必须 在 变量 名 中 强制 定义 前 缀 为 http_、 


sent_http_、upstream_http 、cookie 或 者 arg 。 这 5 类 变量 参见 表 15-1。 


表 15-1 5 类 特殊 HTTP 变 量 


变量 前 组 意 义 解析 方法 
arg_ 请 求 的 URL 参数 ngx http_variable areument 
http_ 请 求 中 的 HTTP 头 部 ngx_ http_variable unknown header in 
sent_http_ 发 送 啊 应 中 的 HITP 头 部 ngx http_variable unknown _ header out 
cookie Cookie 头 部 中 的 某 个 项 ngx_ http_variable_cookie 
upstream http_ 后 端 服务 器 HTTP 啊 应 头 部 ngx http upstream header variable 


5.3) 定义 变量 的 模块 是 希望 变量 可 以 被 快速 访问 的 ， 然 而 ， 它 不 
能 寄 布 望 于 变量 被 索引 ， 因 为 是 否 索引 是 使 用 变量 模块 的 权力 ! 于 是 
定义 的 变量 就 需要 被 hash 为 散 列 表 来 加 速 访问 。 男 一 个 问题 是 5.2 步 的 5 
类 名 字 不 明确 的 HTTP 变 量 怎 么 办 ? 只 有 使 用 变量 的 模块 才 知 道明 确 的 
变量 名 ， 定 义 它们 的 ngx_http_core_module 模 块 不 知道 变量 名 就 无 法 按 
照 变量 名 hash 成 歼 列 表 。 所 以 这 一 步 构 千 散 列表 ， 将 除 表 15-1 的 5 类 变 
量 以 外 的 、 没 有 显 式 设置 不 要 hash 《参见 15.2.2 节 ) 的 变量 生成 到 一 个 
静态 的 开 散 列 表 中 。 


下 面 在 了 解 变量 的 工作 机 制 之 前 ， 还 要 先 介绍 相关 的 结构 体 。 


15.2.2 ”相关 数据 结构 详 壕 


变量 由 变量 名 和 变量 值 组 成 。 对 于 同一 个 变量 名 ， 随 着 场 景 的 不 
同 会 具有 多 个 不 同 的 值 ， 如 条 认为 变量 值 和 变量 名 一 一 对 应 从 而 使 用 
结构 体 表 示 ， 毫 无 疑问 会 有 大 量 内 存 少 费 在 相同 的 变量 名 的 存储 
上 。 因 此 ，Nginx 中 有 一 个 保存 变量 名 的 结构 体 ， 叫 做 
ngx_http_variable_t， 它 人 负责 指定 一 个 变量 名 字符 串 ， 以 及 如 何 去 解 析 


出 相应 的 变量 值 。 所 有 的 变量 名 定义 ngx_http_variable_t 都 会 保存 在 全 


局 唯一 的 ngx_http_core_main_conf {对 象 中 ， 解 析 变 量 时 也 是 围绕 着 它 


MT 


存储 变量 值 的 结构 体 叫 做 ngx_http_variable_value t。 它 既 有 可 能 是 
在 读 取 变 量 值 时 被 创建 出 来 ， 也 有 可 能 是 在 初始 化 一 个 HTTP 请 求 时 就 
预 创建 在 ngx_http_request_t 对 象 中 ， 这 将 视 描述 变量 名 的 
ngx_http_variable_t 结 构 体 成 员 而 定 。 


1. 变 量 的 定义 ngx_http_variable_t 


我 们 先 来 看 看 ngx_http_variable_t 的 结构 : 


struct ngx_http_variable s { 
// name 就 是 字符 串 变 量 名 ， 例 如 


nginx.conf 中 常见 的 


$remote_addr 这 样 的 字符 串 ， 


// 当然 ， 


$ 符 号 是 不 包括 的 


ngx_str name ; 
// 如 果 需 要 变量 最 初 赋值 时 就 进行 变量 值 的 设置 ， 那 么 可 以 实现 


二 | 


set_handler 方 法 。 如 果 我 们 定义 的 


// 内 部 变量 允许 在 


nginx.conf 中 Lb 


set 方式 又 重新 设置 其 值 ， 那 么 可 以 实现 该 方法 (参考 


args 参 数 ， 


// 它 就 是 一 个 内 部 变量 ， 同 时 也 允许 
set 方 式 在 


加 


nginx.conf 里 重新 设置 其 值 ， 详 


15 .4 节 


ngx_http_set_variable_pt set_handler; 
// 每 次 获取 一 个 变量 的 值 时 ， 会 先 调 


get_handler 方 法 ， 所 以 


Nginx 的 官方 模块 变量 的 解析 大 都 


// 在 此 方法 中 完成 


ngx_http_get_variable_pt get_handler; 
// 这 个 整数 是 作为 参数 传递 给 


get_handler、 


set_handler 回 调 方法 使 


uintptr_t data; 
// 变量 的 特性 ， 下 文 详 述 


ngx_uint_t flags; 
// 这 个 数字 也 就 是 变量 值 在 请 求 中 的 缓存 数组 中 的 索引 


ngx_uint_t index; 


/ 
typedef struct ngx_http_variable s ngx_http_variable_t， 


下面 看 看 上 面 的 get_handler 和 set_handler 对 应 的 方法 类 型 
ngx_http_set_variable_pt 是 怎样 的 ， 当 本 章 后 续 定义 新 的 自 有 变量 时 ， 
束 必 须要 实现 相应 的 解析 变量 值 的 方法 : 


typedef void (*ngx_http_set_ variable pt) (ngx_http_request_t *r, 
ngx_http_variable value t *v, uintptr_t data),; 

typedef ngx_int_t (*ngx_http_get_ variable pt) (ngx_http_request_t 

*r,ngx_http_variable value t *v, uintptr_t data); 


可 以 看 到 ， 它 们 均 接 收 3 个 参数 ， 表 示 请 求 的 r， 表 示 灾 量 值 的 v， 
以 及 一 个 可 能 使 用 到 的 参数 data， 这 个 data 也 就 是 定义 变量 名 日 


ngx_http_variable_t 结 构 体 中 的 data 成 员 。 这 两 个 解析 方法 和 data 成 员 在 
15.2.5 攻 会 详细 说 明 。 


flags 成 员 是 一 个 整 型 ， 它 是 按 位 来 设计 的 ， 目 前 仅 有 前 4 位 设 定 了 
含义 ， 所 以 共有 4 种 取 值 的 组 合 ， 这 前 4 位 定义 如 下 所 示 : 


#define NGX_HTTP_VAR_ CHANGEABLE 
#define NGX_HTTP_VAR_NOCACHEABLE 
#define NGX_HTTP_VAR_INDEXED 
#define NGX_HTTP_VAR_NOHASH 


ODPp 


每 个 flags 标 志 位 的 含义 见 表 15-2。 


表 15-2 ”HTTP 变量 名 ngx_http_variable_t 中 的 flags 标 志 位 意 》 


flags 标志 位 当 
表示 对 应 的 变量 值 可 以 改变 ， 也 就 是 对 一 个 请 求 内 的 同一 个 变量 可 以 
反复 地 修改 其 变量 值 反 过 来 说 ， 如 果 没 有 这 个 标志 位 ， 一旦 对 一 个 赋 


oy hp 会 报错 。 对 于 内 部 变量 ， 再 深入 看 看 可 以 知道 ， 
没有 这 个 标志 位 的 变量 ， 是 不 允许 一 次 以 上 定义 同一 变量 名 的 ， 因 为 多 
次 设置 变量 的 解析 方法 与 修改 变量 值 是 等 价 的 ， 我们 常 在 Nginx 启动 时 
误 “ the duplicate…variable”， 就 是 这 个 原因 。 特 别 对 于 15.4 节 
站 绍 的 外 部 变量 ， 它 们 一 定 允 许 反复 修改 同一 变量 的 值 ， 所 以 必须 加 上 
六 标志 位 


NGX HTTP VAR CHANGEABLE 


tie 


flags 标志 位 意 义 
要 缓存 这 个 变量 的 值 ， 每 次 使 用 变量 时 都 需要 重新 解析 。 为 什么 不 
二 ? 因为 有 些 请 求 的 变量 会 在 执行 中 伴随 着 URL 跳 转 等 动作 
反复 改变 ， 如 $uri 这 个 变量 ， 如 果 读 取 到 了 上 一 次 缓存 的 值 是 无 法 确定 
其 是 否 正 而 的 
将 变量 索引 ， 加 速 访问 。 为 什么 又 要 缓存 一 些 变量 的 值 呢 ? 因为 有 些 
变量 在 一 次 请 求 的 执行 中 是 永远 不 变 的 ， 例 如 $request_uri 这 个 变量 
下 示 最 初 接收 自 客户 端的 请 求 URI， 自 然 不 会 变化 ， 那 么 缓存 之 后 的 
久 复 使 用 速度 就 会 更 快 
不 要 把 这 个 变量 hash 到 散 列 表 中 。 为 什么 会 想 着 使 一 个 变量 不 做 散 列 
优化 呢 ? 这 是 因为 散 列 表 也 是 需要 消耗 内 存 的 ， 如 果 某 个 模块 设计 了 一 
NGX HTTP VAR NOHASH 个 可 选 变量 提供 给 其 他 模块 使 用 ， 并 且 要 求 如 果 有 其 他 模块 使 用 该 变量 
就 必须 索引 化 再 使 用 ( 即 不 能 调用 ngx_http_get_variable 方法 来 获取 变 
量 值 )， 这 样 ， 这 个 变量 就 不 用 浪费 散 列 表 的 存储 空间 了 


NGX HTTP VAR NOCACHEABLE 


NGX HTTP VAR INDEXED 


Om 提示 。 Nginx 中 有 一 个 “Embedded Variables” 概 念 ， 例 如 
ngx_http_fastcgi_module 、 en 这 样 
的 “ 咎 入 式 变量 *”。 其 实 ， 这 种 变量 就 是 指 本 模块 提供 了 可 选 变量 仅 供 
其 他 模块 a 使 用 ， 而 其 他 模块 
使 用 时 也 只 能 先 把 变量 索引 化 再 使 用 ， 不 能 依据 散 列 表 使 用 变量 。 这 
种 “ 舱 入 式 变量 ”通常 就 会 指定 flags 中 含有 NGX_HTTP_VAR_NOHASH 
标志 。 这 里 有 两 点 需要 注意 : 中 变量 是 可 选 的 ， 也 就 是 说 ， 使 用 了 该 
模块 的 其 他 Nginx 模 块 不 用 这 个 变量 一 样 可 以 工作 ， 所 以 这 个 变量 不 应 
当 占 用 散 列表 ; Co) 者 其 他 模块 使 用 该 变量 ， 则 必须 移 通 过 
ngx_http_get_variable_index 方 法 把 变量 索引 化 ， 才 能 获取 变量 值 。 


变量 值 n gx_http_variable_value_t 


摘 述 变量 值 的 结构 为 ngx_http_variable_value_t， 实 际 上 等 价 于 


ngx_variable_value ti: 


typedef ngx_variable value t ngx_http_variable_value 七 ; 


看 看 它 包 括 哪些 成 员 : 


typedef struct { 
// 变量 值 必须 是 在 一 段 连续 内 存 中 的 字符 串 ， 值 的 长 度 就 是 


len 成 员 


unsigned len:28; 
// Valid 为 


1 时 表示 当前 这 个 变量 值 已 经 解析 过 ， 且 数据 是 可 用 的 


unsigned valid:1; 
// no_cacheable 为 


1 时 表示 变量 值 不 可 以 被 缓存 ， 它 与 


ngx_http_variable_t 结 构 体 


flags 成 员 


// 里 的 
NGX_HTTP_VAR_NOCACHEABLE 标 志 位 是 相关 的 ， 即 设置 这 个 标志 位 后 


no_cacheable 就 会 为 


1 
unsigned no_cacheable:1; 
// not_found 为 
1 表示 当前 这 个 变量 值 已 经 解析 过 ， 但 没有 解析 到 相应 的 值 
unsigned not_found:1; 
// 仅 由 


于 日 志 格 式 的 字符 转 义 ， 其 他 模块 通常 忽略 这 个 字段 


2 

sy 
lal 
I 


ngx_http_log_module 模 块 使 


unsigned escape:1,; 


// data 就 指向 变量 值 所 在 内 存 的 起 始 地 址 ， 与 


len 成 员 配 合 使 月 


u_char *data; 
} ngx_variable value_t; 


3. 存 储 变 量 名 的 数据 结构 


HTTP 框 架 的 核心 结构 体 ngx_http_core_main_conf t 中 有 3 个 成 员 与 
HTTP 变 量 是 相关 的 ， 如 下 所 示 : 


typedef struct { 


// 存储 变量 名 的 散 列 表 ， 调 


ngx_http_get_variable 方 法 获 


取 未 索引 的 变量 值 时 就 靠 这 


// 散 列 表 找 到 变量 的 解析 方法 


ngx_hash_t 
// 存储 索引 过 的 变量 的 数组 ， 


Nginx 启 动 阶段 从 该 数组 中 获得 索引 


// 这 样 , 在 


variables_hash; 


通常 各 模块 使 用 变量 时 都 会 在 


| 号 ， 


Nginx 运 行 期 内 ， 如 果 变 量 值 没 有 被 缓存 ， 就 会 通过 索引 号 在 


variables 数 组 中 找到 


// 变量 的 定义 ， 


再 解析 出 变量 值 


ngx_array_t 
// 用 于 构造 


variables; 


variables_hash 散 列表 的 初始 结构 体 


ngx_hash_keys_arrays_t 
} ngx_http_core_main_conf 


*variables_keys; 
t; 


这 3 个 成 员 中 ，variables_hash、variables 会 在 Nginx 的 正常 运行 中 使 
用 ， 而 variables_keys 纯 粹 只 在 Nginx 启 动 时 临时 用 一 下 ， 它 只 是 用 于 构 


建 variables_hash 散 列表 ，variables_hash 成 功 生 成 后 variables_keys 就 功 成 
号 退 了 。 


4. 绥 存 变 量 值 的 数据 结构 


变量 值 如 果 可 以 被 缓存 ， 那 么 它 一 定 只 能 缓存 在 每 一 个 HTTP 请 求 
内 ， 对 于 Nginx 这 样 一 个 Web 服 务 器 来 说 ， 不 可 能 为 不 同 的 HTTP 请 求 缓 
存 同一 个 值 。 因 此 缓存 的 变量 值 瓯 在 表述 一 个 HITP 请 求 的 
ngx_http_request_t 结 构 体 中 ， 如 下 : 


struct ngx_http_request _s { 
// variables 数 组 存储 所 有 序列 化 了 的 变量 值 ， 数 组 下 标 即 为 索引 号 


ngx_http_variable value 上 *variables; 


当 HTTP 请 求 刚 到 达 Nginx 时 ， 就 会 创建 缓存 变量 值 的 variables 数 
组 ， 如 下 : 


ngx_http_request 七 * 
ngx_http_create_request(ngx_connection t *c) 


{ 

ngx_http_request_t TP 

ngx_http_core main conf_t *cmcf; 

cmcf = ngx_http_get_ module main_conf(r, ngx_http_core_ module); 
// 缓存 变量 值 的 


variables 数 组 下 标 ， 与 索引 化 的 、 表 示 变 量 名 的 数组 


cmcf->variables 下 标 ， 


// 它们 是 一 一 对 应 的 


r->variables = ngx_pcalloc(r->pool, cmcf->variables.nelts 
sizeof (ngx_http_variable_value_ t)); 


一 旦 某 个 变量 的 ngx_http_variable_value_t 值 结构 体 被 缓存 ， 取 值 时 
束 会 优先 使 用 它 。 


5. 内 存 布 局 


了 解 了 相应 的 结构 体 后 ， 我 们 可 以 从 它们 在 Nginx 内 存 中 如 何 布局 
入 手 ， 掌 握 其 用 法 。 


欲 了 解 其 内 存 布局 ， 当 然 首 先 从 ngx_http_core_main_conf t 中 的 3 个 
成 员 来 串 起 各 结构 体 。variables_keys 仅 用 于 构造 variables_hash 散 列表 ， 
它 也 是 Nginx 构 造 散 列 表 的 必 经 步骤 ， 读 者 朋友 可 以 参考 第 7 章 ， 这 里 
不 再 介绍 。 我 们 重点 看 看 variables_hash 散 列表 中 的 变量 与 variables 索 引 
数组 中 的 变量 有 何 关联 ， 参 见 图 15-2。 


ngx_hash_elt_t 


开 散 列表 


ngx_http_variable_t 


ngx_http_core_main_conf ft 


ET 
variables_hash 


variables_keys 


variables 


bE 


flags (无 NGX_HTTP_VAR_NOHASH ) 


| 


flags 同 时 满足 二 者 的 同名 变量 ，flags 外 的 参数 必须 完全 一 致 


索引 0 索引 1 索引 2 索引 3 索引 4 
sl 
n i ariable_t 构 成 的 数组 
所 


% 
NS 


ngx_http_variable_t 


、 
、 I 


|flags ( 含 NGX_HTTP_VAR_INDEXED ) 


图 15-2 ”定义 变量 的 ngx_http_variable_t 结 构 体 在 内 存 中 的 布局 


可 以 看 到 ， 散 列表 与 索引 数组 中 都 存放 着 各 目的 
ngx_http_variable _t 结 构 体 ， 即 使 name 相 同 的 同一 个 变量 ， 如 果 既 被 索 
引 又 被 hash 的 话 ， 仍 然 会 有 两 份 ngx_http_variable_t 结 构 体 ， 除 了 flags 成 
员 会 有 不 同 外 ， 它 们 的 其 他 成 员 都 是 相等 的 。 使 其 各 成 员 “ 相 等 ”这 个 
操作 是 在 图 15-1 的 第 5.1 步 又 的 ngx_http_variables_init_vars 方 法 完成 的 ， 
感 兴趣 的 朋友 可 以 阅读 源 代 码 。 


这 里 的 含义 怠 是 ， 同 一 个 变量 名 称 可 以 同时 既 被 索引 又 被 hash， 但 
一 定 只 有 一 种 解析 变量 的 方法 ， 所 以 ， 同 一 变量 可 以 同时 拥有 两 个 
ngx_http_variable_t 结 构 体 。 


无 论 是 索引 还 是 hash， 都 必须 针对 明确 的 变量 名 。 可 是 在 表 15-1 中 
却 有 5 类 特殊 变量 ， 它 们 只 是 前 级 固定 为 http_、sent_http_、 
upstream_http_、cookie 或 者 arg_， 唯 有 在 模块 使 用 1 个 具体 的 变量 时 才 
能 确定 完整 的 变量 名 称 。 确 定 了 完整 名 称 的 特殊 变量 是 可 以 被 索引 
的 ， 却 不 应 该 被 hash 到 散 列 表 中 ， 为 什么 呢 ? 因为 进入 散 列 表 的 变量 都 
是 由 模块 重 定义 解析 方法 的 ， 而 这 5 类 特殊 变量 则 可 以 复 用 HTTP 框 架 
已 经 准备 好 的 通用 解析 方法 。 所 以 索引 变量 、 散 列表 变量 、 特 殊 变 量 
会 组 合 为 5 种 关系， 如 图 15-3 所 示 。 


了 、- 此 . 7 
variables_hash 存 放 的 hash 过 的 变量 


同时 被 hash 和 有 索 
国 | | 的 变量 


variables 存 放 的 索引 过 的 变量 


被 索引 的 特殊 变量 


5 类 特殊 变量 


图 15-3 ”索引 变量 、hash 变 量 、 特 殊 变 量 则 的 集合 关系 


图 15-3 中 有 4 个 要 点 : 
1) 同一 个 变量 可 以 同时 被 hash 和 索引 。 


2) 变量 并 非 要 么 在 散 列 表 中 ， 要 么 在 索引 数组 中 。 对 于 特殊 变 
量 ， 是 可 以 绕 开 二 者 用 ngx_http_get_variable 方 法 获取 其 值 的 。 


3) 对 于 特殊 变量 ， 是 可 以 使 用 索引 的 方式 来 获取 其 值 的 ， 这 也 是 
最 常用 的 方式 。 


4) 不 要 重 定 义 特殊 变量 ， 重 定义 的 特殊 变量 可 能 存在 于 散 列表 中 
(未 设置 NGX_HTTP_ VAR _NOHASH 标 志 位 ) 。 


下 面 我 们 通过 图 15-4 来 看 看 索引 过 的 变量 在 内 存 中 是 怎么 使 用 的 。 


变量 的 索引 由 两 部 分 组 成 ， 一 是 定义 变量 的 ngx_http_variable_t 结 
构 体 构成 的 索引 数组 ， 二 是 描述 变量 值 的 ngx_http_variable_value_t 结 构 
体 构成 的 数组 。 前 者 在 Nginx 只 有 全 局 的 唯一 一 份 ， 存 储 在 
ngx_http_core_main_conf t 结 构 体 的 variables 中 ; 后 者 对 每 一 个 HTTP 请 
求 都 会 有 一 份 ， 存 储 在 ngx_http_request t 结 构 体 的 variables 中 。 这 两 者 
间 同 属于 一 个 变量 的 名 字 、 值 在 各 目 数 组 中 的 索引 号 都 是 一 一 对 应 
的 。 


想 以 索引 方式 使 用 变量 的 模块 ， 部 会 在 模块 初始 化 阶段 获得 索引 
号 ， 在 Nginx 运 行 中 、HTTP 请 求 到 达 时 ， 则 会 根据 这 个 索引 号 ， 要 人 么 


从 ngx_http_variable_t 构 成 的 数组 中 找到 变量 定义 并 使 用 get_handler 方 法 
解析 出 变量 值 (如 有 果 flags 参 数 指明 可 以 缓存 ， 那 么 还 会 缓存 到 请 求 
中 ) ， 要 么 从 ngx_http_variable_value_t 构 成 的 数组 中 直接 获得 缓存 的 变 
量 值 。 


这 个 数组 主要 用 于 存 
放 所 有 被 索引 过 的 变 
量 定义 ， 特 别 是 其 解 
析出 变量 值 的 方法 


gx_http_core_main_conf_t 


了 ”下 
variables_keys 
variables_hash 


索引 0 索引 1 索引 2 索引 3 索引 4 


/ 
ngx_htt p_variable, {构成 | 的 数组 |/ 
Pg 


ngx_http_variable_t 


we | TITTTE 
2 et 


index 索 引号 == 


get_handler 解 析 值 


设置 值 获得 缓存 值 


ngx_http_request_t 


索引 0 ; 索引 1 : 索引 2 ; 索引 3 : 索引 4 


ngx_http_request_t 


这 样 的 数组 
用 于 缓存 变 
量 值 ， 每 个 
请 求 都 有 访 
数组 


ingx_http; variable_value 


构成 的 变量 值 预 分 配 数组 


ngx_http_variable_value + 


len， 变 量 值 的 长 度 
data， 指 向 变量 值 


图 15-4 索引 过 的 变量 内 存 使 用 示意 图 


每 一 个 HTTP 请 求 都 必须 为 所 有 缓存 的 变量 建立 
ngx_http_variable_value_t 数 组 ， 这 似乎 有 些 内 存 浪费 ， 因 此 ， 不 使 用 索 
引 而 是 散 列 表 来 使 用 变量 也 是 可 以 的 ， 此 时 其 内 存 布局 如 图 15-5 所 示 。 


ngx_http_core_main_conf ft 


ngx_hash_elt_t 


variables 


variables_keys 


variables_hash 


开 散 列表 


使 用 变量 的 模块 


根据 hashkey 和 name 查 询 散 列表 


name 


index | 


索引 过 的 变量 会 先 取 组 存 值 flags 


get_handler 


ngx_http_request_t 


iabl I | | : 
: | ; 未 索引 变量 则 构造 新 的 ngx_http_variable_value 


len， 变 量 值 的 长 度 


data， 指 向 变量 值 


len， 变 量 值 的 长 度 
data， 指 癌变 量 值 


图 15-5” 散 列 过 的 变量 内 存 使 用 示意 图 


此 时 ， 使 用 变量 的 模块 不 用 在 Nginx 初 始 化 阶段 做 些 什 么 ， 只 要 这 
个 变量 已 经 有 模块 定义 过 ， 那 么 在 处 理 请 求 时 ， 仅 需要 把 变量 名 字符 
串 按照 hash 方 法 求 出 散 列 值 ， 就 可 以 在 ngx_http_core_main_conf_t 结 构 
体 的 variables_hash 散 列表 中 找到 定义 变量 的 ngx_http_variable_t 结 构 
体 ， 如 果 其 flags 成 员 指明 变量 是 被 索引 的 ， 那 么 会 根据 index 成 员 直 接 
向 请 求 的 variables 数 组 里 获得 预 分 配 的 ngx_http_variable_value_{t 结 构 
体 ， 这 个 变量 值 若 没有 解析 过 ， 就 会 用 该 结构 体 传 给 get_handler 方 法 解 
析 、 缓 存 (如 果 可 以 的 话 ) 。 如 果 flags 成 员 没有 说 明 变 量 被 索引 过 ， 
那么 就 会 在 请 求 的 内 存 池 里 新 分 配 1 个 ngx_http_variable_value_t 结 构 
体 ， 用 于 传递 给 get_handler 方 法 解析 、 承 载 变量 值 。 


15.2.3 ”定义 变量 的 方法 


定义 新 的 内 部 变量 时 ， 通 过 ngx_http_add_variable 方 法 进行 ， 其 定 
义 如 下 : 


ngx_http_variable 七 * 
ngx_http_add_variable(ngx_conf_t *cf, ngx_str_t *name, ngx_uint_t flags); 


在 15.2.1 广 已 经 介绍 过 ， 添 加 变量 必须 是 在 preconfiguration 回 调 方 
法 中 ， 第 1 个 参数 cf 直接 把 preconfiguration 中 的 ngx_conf_t 指 针 传 入 即 
可 ，cf 的 用 途 有 两 个 : 定义 新 变量 一 定 会 放 到 全 局 唯一 的 
ngx_http_core_main_conf t 结 构 体 ， 参 数 cf 可 以 找到 这 个 全 局 配置 结构 


体 ; 分 配 变量 相关 结构 体 的 内 存 时 ， 可 以 用 cf 的 内 存 池 。 第 2 个 参数 就 
是 变量 的 名 称 。 第 3 个 参数 等 价 于 ngx_http_variable_t 中 的 flags 成 员 。 


返回 值 就 是 已 经 准备 好 的 、 用 于 定义 变量 的 ngx_http_variable_t 结 
构 体 。 此 时 ， 这 个 结构 体 的 name 和 flags 成 员 已 经 设置 好 了 ， 这 时 需要 
定义 变量 模块 做 的 工作 就 是 指定 解析 方法 ， 包 括 指定 get_handler、 
set_handler 〈 很 少 设置 ) 、data (如 果 有 必要 的 话 ) 。 在 15.2.5 节 中 再 来 
介绍 如 何 实 现 解 析 方 法 。 


@ 注意 ”如果 这 个 变量 曾经 被 其 他 模块 添加 过 ， 那 么 此 时 的 返 
回 值 ngx_http_variable_t 就 是 其 他 模块 已 经 设置 过 的 对 象 ， 它 的 
get_handler 等 成 员 可 能 已 经 设置 过 了 “。 开 发 模块 靳 变量 时 应 当 妥 善 处 理 


这 种 变量 名 冲突 问题 。 


15.2.4 使 用 变量 的 方法 


使 用 变量 时 会 使 用 表 15-3 中 所 列 的 4 个 方法 。 


使 用 变量 时 有 两 种 方式 第 一 种 方式 是 索引 变量 ， 表 15-3 的 前 3 个 
方法 都 只 用 于 索引 变量 ， 索 引 变量 效率 更 高 ( 且 可 以 被 缓存  ， 但 可 
能 会 消耗 稍 多 点 的 内 存 ， 第 二 种 方式 古 非 索 引 的 、hash 过 的 变量 ， 
ngx_http_get_variable 方 法 用 于 此 目的 。 


人 @@ 注意 ”如 果 这 个 变量 被 索引 过 ， 那 么 ngx_http_get_variable 方 
去 会 优先 在 ngx_http_request_t 中 缓存 变量 值 鸭 variables 数 组 中 的 获取 
值 。 是 否 被 索引 过 的 依据 就 是 检查 flags 参 数 是 否 含有 
NGX_HTTP VAR INDEXED 标 志 位 9 


表 15-3 ”获取 HTTP 变 量 值 的 3 个 方法 


方法 名 总 义 
和 余 置 变量 被 索引 ， 并 获得 索引 号 ， 它 是 使 用 ngx_http_get_indexed variable、 
ngx i flushed_variable 方法 的 前 和 7” 
调用 它 意味 着 这 个 变量 会 被 频繁 地 使 用 ， ginx 处 理 这 个 变量 时 效率 更 
， 体 现在 : 
ngx http get variable index e 变量 值 可 以 被 缓存 ， 重 复读 取 时 不 用 每 次 解析 
e 定义 变量 的 解析 方法 时 ， 可 以 通过 索引 直接 找 色 该 方法 进行 解析 ， 而 不 是 


通过 操作 散 列 表 
e Nginx 初始 化 HITP 请 求 时 ， 就 需要 为 这 个 变量 预 分 配 ngx_http_variable_ 
value t 变量 值 结构 体 
根据 ngx_http get variable index 得 到 的 索引 号 ， 获 取 被 索引 过 的 变量 的 
nin tp, get ji di 值 。 若 变量 被 解析 过 一 次 后 其 值 是 全 被 缓存 的 ， 这 样 该 方法 再 次 调用 后 将 会 
- - 直接 获取 缓存 过 的 值 ， 而 不 是 重新 解析 。 这 个 方法 是 忽略 NGX_HTTP VAR_ 
NOCACHEABLE 标志 位 的 
与 ngx_http_get_indexed_variable 相似 ， 区 别 是 : 如 果 flags 中 设置 了 NGX 
wa HTTP VAR NOCACHEABLE 标 志 位 ， 那 么 ngx http_get indexed Variable 方 
法 会 忽略 这 个 标志 位 ， 本 方法 则 会 不 使 用 已 经 缓存 的 变量 值 ， 每 次 取 值 时 皆 重 


新 解析 
根据 变量 名 称 ， 从 被 hash 过 的 散 列 表 里 找到 相应 的 变量 并 调用 其 解析 方法 
ngx http get Variable 获得 值 ， 这 里 不 存在 缓存 变量 值 的 可 能 。 同 时 若 变量 是 属于 表 15-1 里 的 $ 种 


特殊 变量 ， 也 可 以 从 本 方法 中 获取 解析 出 的 值 


15.2.5 “如何 解析 变量 


首 移 回 顾 一 下 解析 变量 的 主要 方法 get_handler 的 方法 原型 : 


typedef ngx_int_t (*ngx_http_get variable pt) (ngx_http_request_t 
*r,ngx_http_variable value t *v, uintptr_t data); 


参数 r 和 data 都 用 来 帮助 生成 变量 值 ， 而 v 则 是 存放 值 的 载体 。 结 构 
体 v 已 经 分 配 好 内 存 了 《调用 get_handler 的 函数 负责 ) ， 当 然 分 配 好 的 
内 存 中 是 不 包括 字符 串 变 量 值 的 。 可 以 使 用 请 求 r 的 内 存 池 来 分 配 新 的 
内 存放 置 变 量 值 ， 这 样 请 求 结束 时 变量 值 束 会 锌 释放， 可 见 变 量 值 的 
生命 周期 与 请 求 是 一 任 的 ， 而 变量 名 则 不 然 。 将 参数 v 的 data 和 len 成 员 
指 疝 变 量 值 字符 串 即 完成 了 变量 的 解析 。 这 一 过 程 本 来 共性 特征 并 不 
多 ， 然 而 uintptr_t data 参 数 却 有 一 些 通 用 的 “玩法 ”， 本 和 则 简要 介绍 一 
Fs 


(1) uintptr_t data 参 数 不 起 作用 


如 果 只 是 生成 一 些 和 用 户 请 求 无 关 的 变量 值 ， 例 如 当前 时 间 、 系 
统 负载 、 磁 盘 状 况 等， 那么 这 与 读者 朋友 的 需求 有 关 ， 使 用 各 种 手法 
获得 变量 值 后 赋 给 参数 v 的 data 和 len 成 员 即 可 。 或 者 说 ， 
ngx_http_request_t*r 中 的 成 员 已 经 足够 解析 出 变量 值 了 ，data 参 数 不 用 
也 罢 。 举 个 例子 ，HTTP 框 架 提 供 了 一 个 变量 一 body_bytes_sent， 表 
示 一 个 请 求 的 响应 包 体 长 度 ， 常 用 在 access.log 访 问 日 志 中 ， 它 的 解析 
方法 设置 为 ngx_http_variable_body_bytes_sent，uintptr_t data 因 为 不 使 用 
则 设 为 0， 如 下 所 示 : 


static ngx_http_variable t ngx_http_core variables[] = { 
{ngx_string("body_bytes_sent"),NULL, 
ngx_http_variable_body_bytes_sent, 

0, 0, 0 小 
} 


而 ngx_http_variable body_bytes_sent 解 析 响 应 包 体 长 度 变量 的 值 时 
仅 从 请 求 r 中 就 获取 到 足够 信息 了 ， 如 下 : 


static ngx_int_t 
ngx_http_variable_body_bytes_sent(ngx_http_request_t *r, 
ngx_http_variable value t *v, uintptr_t data) 


off_t sent; 
// 发 送 的 总 响应 值 减 去 响应 头 部 即 可 


sent = r->connection->sent - r->header_size; 


(2) uintptr_t data 参 数 作 为 指针 使 用 


uintptr_t 是 一 个 可 以 放置 指针 的 整 型 ， 所 以 ，uintptr_t data 怠 被 设计 
为 既 用 来 做 整 型 偏 移 值 ， 又 用 来 做 指针 。 下 面 看 看 HTTP 框 染 把 data 用 
来 做 指针 的 一 个 例子 ， 我 们 知道 有 5 类 特殊 变量 ， 它 们 以 特殊 的 字符 串 
打头 ， 例 如 http_ 或 者 sent_http_ ， 实 际 上 每 一 个 这 样 的 变量 其 解析 方法 
都 大 同 小 异 ， 允 有 历 解 析出 来 的 r>headers_in.headers 或 者 r- 
>headers_in.headers 数 组 ， 找 到 变量 名 再 迟 回 其 值 即 加。 那么 怎样 设计 
通用 的 解析 方法 呢 ? 答案 就 是 把 uintptr_t data 作 为 指针 指向 实际 的 变量 
名 字符 串 。 如 下 所 示 ， 当 出 现 了 如 http_ 这 样 的 变量 被 模块 使 用 时 ， 就 
把 data 作 为 指针 来 保存 实际 的 变量 名 字符 串 v[i].name 

(ngx_http_variables_init_vars 初 始 化 特殊 变量 时 的 代码 段 ) 。 


If (ngx_strncmp(v[il.name.data, "http_", 5) == 0) { 
v[i].get_handler = ngx_http_variable _ unknown_header_in; 
v[il.data = (uintptr_t) &v[i].name; 


} 


而 解析 变量 的 get_handler 方 法 再 把 data 转 为 ngx_str_t 字 符 串 变量 名 
即 可 ， 如 下 : 


static ngx_int_t 
ngx_http_variable_unknown_header_in(ngx_http_request _t *r, 
ngx_http_variable value t *v, uintptr_t data) 


return ngx_http_variable unknown_header(v, (ngx_str_t *) data, &r- 
>headers_in.headers.part, sizeof("http_") - 1); 


} 


ngx_http_variable_unknown_header 方 法 就 只 是 遍历 ngx_list_t 链 表 类 
型 的 headers 数 组 ， 找 到 符合 变量 名 的 头 部 后 ， 将 其 值 作为 变量 值 返回 
BA] 。 


(3) uintptr_t data 参 数 作 为 序列 化 内 存 的 相对 偏 移 量 使 用 


很 多 时 候 ， 变 量 值 很 有 可 能 就 是 原始 的 HTTP 字 符 流 中 的 一 部 分 连 
续 字 符 串 ， 如 果 能 够 复 用 ， 就 不 用 为 变量 的 字符 串 值 再 次 分 配 、 找 贝 
内 存 了 。 另 外 各 HTTP 模 块 在 使 用 get_handler 解 析 变量 时 ，HTTP 框 架 可 
能 在 请 求 的 自动 解析 过 程 中 已 经 得 到 了 需要 的 变量 值 ， 这 部 分 计算 工 
作 也 可 以 不 用 再 做 一 遍 。 那 么 能 不 能 据 此 两 点 加 快 解析 速度 呢 ? data 参 
数 作为 整 型 设计 的 目的 就 在 于 此 。 


HTTP 框 架 中 会 解析 很 多 请 求 的 头 部 ， 如 http_host、http_user_agent 
等 ， 它 们 实际 上 已 经 在 请 求 尖 部 接收 完整 时 就 已 经 解析 完了 ， 如 果菜 
个 Nginx 模 块 需要 使 用 这 个 变量 ， 完 全 可 以 复 用 ， 能 够 复 用 的 依据 在 


于 : HTTP 框 架 解 析 后 的 变量 值 ， 其 定义 成 员 在 ngx_http_request_t 结 构 


体 里 的 位 置 是 固定 不 变 的 


。 这 样 就 可 以 用 data 承 载 偏 移 量 直接 把 


ngX_http_variable_value_t 里 的 data、len 指 加 变量 值 字 符 串 即 可 。 例 如 主 
机 名 变量 http_host 其 实 正 对 应 着 ngx_http_request_t 结 构 体 里 的 headers_in 
成 员 的 host 成 员 ， 而 访问 浏 贤 侨 http_user_agent 变 量 则 对 应 着 
ngx_http_request_t 结 构 体 里 的 user_agent 成 员 ， 它 们 的 解析 方法 都 是 专 
门 用 于 找 出 已 经 解析 过 HTTP 头 部 的 变量 的 ngx_http_variable_header 方 
法 ， 而 data 则 是 偏 移 量 ， 如 下 : 


static ngx_http_variable _t 


ngx_http_core_ variables[] = { 


{ ngx_string("http_host"), 
offsetof(ngx_http_requ 
{ ngx_string("http_user_age 
offsetof(ngx_http_requ 
上 


NULL, ngx_http_variable_header, 
est_t, headers_in.host), 0, 0 }, 
nt"), NULL, ngx_http_variable_header, 
est_t, headers_ in.user_agent), 0, 0 }, 


在 第 4 章 我 们 已 经 介绍 过 offsetof 方 法 ， 它 接收 两 个 参数 ， 并 认为 第 


1 个 参数 是 一 个 struct 结 构 体 ， 第 2 个 参数 是 其 成 员 ， 返 回 的 束 是 成 员 在 


其 结构 体 中 的 偏 移 量 。 看 


static ngx_int_t 
ngx_http_variable_header (ng 
uintptr_t data) 


ngx_table elt t *h; 
// data 偏 移 量 就 是 解析 过 的 


ngx_table_elt_t 类 型 的 成 员 ,， 在 


ngx_http_request_t 结 构 体 中 的 1 


h = *(ngx_table elt t * 
if (h) { 
// 将 


len 和 


看 ngx_http_variable_header 方 法 做 了 些 什么 : 


x_http_request_t *r, ngx_http_variable value t *V， 


户 移 量 


*) ((char *) r + data); 


data 指 向 字符 串 值 


VvV->len = h->value.1en,; 
VvV->valid = 1; 
VvV->no_cacheable = 0; 
V->not_found = 0; 
V->data = h->value.data; 
} else { 
V->not_found = 1; 
} 


return NGX_OK; 


15.2 节 已 经 完整 介绍 了 定义 内 部 变量 的 方法 ， 本 世 我 们 扩展 15.17F 
的 例子 ， 定 义 新 的 内 部 变量 供 其 他 模块 使 用 《就 像 媒 入 式 变 量 ， 即 本 
模块 配置 项 是 不 支持 该 变量 的 ， 例 如 使 ngx_http_ log_module 模 块 可 
以 将 新 定义 的 变量 记录 到 access.log 访 问 日 志文 件 中 。 


我 们 定义 的 这 个 新 的 舱 入 式 内 部 变量 叫做 is_chrome， 顾 名 思 义 ， 
惑 是 表示 这 个 请 求 是 否 来 目 于 chrome 浏 顺 器 。 首 先 ， 要 在 源 代码 中 定 


V 文人 个 三 旦 名 和 
义 这 个 变量 名 称 ， 如 下 : 
static ngx_str_t new varaible is chome = ngx_string("is_chrome"); 


在 15.2.1 节 中 我 们 说 过 ， 必 须 在 preconfiguration 阶 段 定义 变量 ， 所 
以 先 要 声明 一 个 在 preconfiguration 阶 段 执行 的 方法 : 


static ngx_int_t ngx_http_mytest_add_variable(ngx_conf t *cf); 


并 在 ngx_http_module_t 中 新 增 调用 ngx_http_mytest_add_variable 方 
法 ， 如 下 : 


static ngx_http_module t ngx_http_testvariable module ctx = 


ngx_http_mytest_add_variable, /* preconfiguration */ 
ngx_http_mytest_init, /* postconfiguration */ 


】 


下 面 我 们 开始 实现 添加 变量 的 ngx_http_mytest_add_variable 方 法 : 


ngx_http_mytest_add_variable 方 法 : 


static ngx_int_t 
ngx_http_mytest_add_variable(ngx_conf_t *cf) 


ngx_http_variable _t *V; 
// 添加 变量 


v = ngx_http_add_ variable(cf，&new_ varaible is chome, 
NGX_HTTP_VAR_CHANGEABLE); 
if (v == NULL) { 
return NGX_ERROR ， 


} 
// 如 果 


is_chrome 这 个 变量 没有 被 添加 过 ， 那 么 


get_handler 就 是 


NULL 空 指针 


v->get_handler = ngx_http_ischrome_variable; 
// 这 里 的 


data 成 员 没 有 使 用 价值 ， 故 设 为 


0 
V->data = 0; 
return NGX_OK， 


最 后 定义 is_chrome 变 量 的 解析 方法 : 


static ngx_int_t 

ngx_http_ischrome_variable(ngx_http_request_t *r, ngx_http_variable value t *yv, 
uintptr_t data) 
// 实际 上 


r->headers_in.chrome 已 经 根据 


user_agent 头 部 解析 过 请 求 是 否 来 自 于 


chrome 浏 览 器 


If (r->headers_in.chrome) { 
*vV = ngx_http_variable_true_value,; 
return NGX_OK; 


*v = ngx_http_variable_null_ value; 
return NGX_OK; 


如 此 ，is_chrome 变 量 已 经 在 这 个 模块 中 添加 a 到 Nginx 中 了 ， 然 而 
这 个 测试 模块 却 没 有 相关 的 配置 项 直接 使 用 该 变量 。 所 以 只 有 其 他 使 
用 到 该 变量 的 模块 才 可 能 提供 相应 的 配置 项 在 nginx.conf 中 供 大 家 使 
用 。 例 如 ，access_log 里 可 以 这 么 配置 : 


log_ format main '$remote addr - [$time local] "$request" ' 
'$status $body_bytes_sent "$http_referer" ' 
'"$http_user_agent" ischrome: $is_chrome’ 


这 样 就 会 记录 请 求 是 否 来 自 于 chrome。 其 实 这 个 变量 也 就 是 15.1 
刀 


15.4 ”外 部 变量 与 脚本 引擎 


ngx_http_rewrite_module 模 块 使 用 了 Nginx 的 脚本 引擎 ， 提 供 了 外 
部 变量 的 功能 。"“ 外 部 变量 ?与 前 几 节 介绍 的 变量 有 什么 不 同 呢 ? 这 里 
的 定义 是 ， 变 量 名 称 是 在 nginx.conf 的 配置 文件 里 声明 的 (不 像 在 C 源 
代码 中 定义 的 内 部 变量 ) ， 且 在 配置 文件 里 确定 了 变量 的 赋值 。 


ngx_http_rewrite_module 模 块 定义 的 外 部 变量 格式 为 : 


set $variable value,; 


这 一 行 配 置 通过 set 关 键 字 定义 了 一 个 在 nginx.conf 中 指定 的 新 变量 
variable， 并 将 其 赋值 为 value。 这 个 value 是 一 个 文本 字符 串 ， 实 际 上 
value 中 还 可 以 含有 多 个 要 量 ， 也 可 以 是 变量 与 文本 字符 串 的 组 合 。 这 
种 外 部 变量 的 定义 非 第 有 用 ， 尤 其 古 配 合 rewrite 重 定 丫 URL、if 关 键 子 
等 ， 可 以 起 到 意 想 不 到 的 效果 ， 我 们 可 以 在 互联 网 上 找到 多 种 巧妙 的 
用 法 ， 通 过 修改 nginx.conf 就 得 到 了 丰富 的 功能 。 


很 多 程序 员 认为 nginx.conf 的 设计 有 些 脚本 语言 的 味道 ， 因 为 它 可 
以 定义 变量 、 可 以 跳 转 到 不 同 的 程序 段 执行 、 拥 有 论文 样 的 判断 型 配置 
等 (当然 这 些 都 是 ngx_http_rewrite_module 模 块 提供 的 ， 使 用 它们 必须 
要 将 ngx_http_rewrite_module 模 块 编译 进 Nginx) 。 但 这 1 门 “ 脚 本 语言 " 却 


有 些 独特 的 味道 ， 与 编译 型 语言 相 比 ， 它 有 是 不 存在 预 编 译 这 个 步 又 
的 ， 只 有 Nginx 局 动 过 程 中 才 会 把 脚本 式 配 置 项 载 入 Nginx 进 程 中 〈 当 
然 ， 把 Nginx 的 局 动 理 解 为 “编译 ” 步 又 的 话 ， 它 其 实 更 像 吓 编译 语 

言 ) 。 与 解释 型 语言 相 比 ， 它 又 不 是 执行 到 某 一 行 脚本 时 才 会 解释 
它 ， 而 是 Nginx 一 局 动 束 会 检查 配置 项 的 合法 性 ， 并 把 所 有 的 脚本 式 语 
句 都 “解释 ”为 C 程 序 ， 等 等 HTTP 请 求 到 来 时 执行 。 


外 部 变量 虽然 在 Nginx 局 动 时 束 被 编译 为 C 代 码 ， 但 它们 是 在 请 求 
处 理 过 程 中 才 被 执行 、 生 效 的 。 就 像 下 面 这 段 配置 : 


location /image/ { 
set imagewidth 100; 


} 
location / { 


在 这 段 配置 里 ， 只 有 请 求 匹配 到 /image/ 后 ， 外 部 变量 imagewidth 才 
会 被 定义 并 被 赋值 为 100 (或 者 imagewidth 已 经 被 定义 过 而 被 修改 值 为 
100) ， 这 样 之 后 的 脚本 、 模 块 才 可 以 使 用 imagewidth 变 量 。 反 之 ， 请 
求 没有 匹配 到 /image/ 就 不 会 执行 这 上段 set 脚 本 。 


因此 ， 外 部 变量 的 设计 可 以 总 结 为 两 个 步骤 : 


1) Nginx 启 动 时 将 配置 文件 中 的 set 脚 本 式 配置 编译 为 相关 的 数据 
与 执行 方法 。 


2) 接收 到 HTTP 请 求 时 ， 在 
NGX_HTTP_ SERVER_REWRITE_PHASE 或 者 
NGX_HTTP_REWRITE_PHASE 阶 段 中 查找 匹配 了 的 location 下 是 否 有 
待 执行 的 脚本 ， 如 果 有 则 依次 执行 。 


本 廊 并 不 会 完整 介绍 ngx_http_rewrite_module 模 块 用 到 的 所 有 脚本 
语法 ， 以 及 Nginx 脚 本 引擎 的 完整 用 法 。 然 而 外 部 变量 已 经 足够 有 代表 
性 了 ， 通 过 上 面 的 配置 作为 例子 介绍 其 工作 原理 ， 读 者 朋友 就 可 以 清 
晰 地 了 解 到 脚本 引擎 的 用 法 ， 进 而 可 以 展开 阅读 
ngx_http_rewrite_module 模 块 源 代码 了 解 更 多 的 细 广 。 


15.4.1 相关 数据 结构 


同一 段 脚本 被 编译 进 Nginx 中 ， 在 不 同 的 请 求 里 执行 时 效果 是 完全 
不 同 的 ， 所 以 ， 每 一 个 请 求 都 必须 有 其 独 有 的 脚本 执行 上 下 文 ， 或 者 
称 为 脚本 引擎 ， 这 是 最 关键 的 数据 结构 。 在 Nginx 中 ， 是 由 
ngx_http_script.h 文 件 里 定义 的 ngx_http_script_engine_t 结 构 体 充当 这 一 
角色 ， 如 下 所 示 : 


typedef struct { 
// 指向 待 执 行 的 脚本 指令 


har *1ip; 


u_c 
// 变量 值 构成 的 栈 


http_variable value t *sp; 


ngx_ 
// 脚本 引擎 执行 状态 


ngx_int_ 


t status; 
// 指向 当前 脚本 引 


擎 所 属 的 


HTTP 请 求 


ngx_http_request_t *request,; 


} ngx_http_script_engine_t; 


我 们 来 看 看 与 外 部 变量 相关 的 4 个 成 员 。 


ngx_http_variable_value_t*sp 是 一 个 栈 。 我 们 知道 任何 语言 都 需 
要 “ 栈 ” 这 样 一 个 数据 结构 作为 编译 工具 ， 例 如 在 函数 的 调用 、 表 达 式 
的 解析 时 。 对 set 定 义 的 外 部 变量 也 一 样 ， 它 需要 sp 这 个 栈 来 存放 变量 
值 。 栈 当然 也 有 大 小 ， 目 前 的 默认 大 小 为 10 个 变量 值 。 


reduest 很 简单 ， 指 网 了 HTTP 请 求 。 


u_char*ip 可 以 想象 为 卫 寄 存 器 ， 因 为 它们 的 目的 是 一 致 的 ， 都 是 
指向 下 一 行将 要 执行 的 代码 。 然 而 让 却 是 一 个 u_char* 类 型 ， 它 指向 的 
类 型 是 不 确定 的 。 它 指向 的 一 定 是 待 执行 的 脚本 指令 ， 难 道 没有 规律 
吗 ? 用 面向 对 和 象 的 语言 来 说 ， 它 指 同 的 是 实现 了 
ngx_http_script_code_pt 接 口 的 类 。 当 然 C 语 言 里 没有 接口 、 类 的 概念 ， 
在 C 语 言 里 要 想 实现 上 述 目的 ， 通 徊 会 用 拘 合 结构 体 的 方法 ， 比 如 表示 
接口 的 结构 体 A， 要 放 在 表示 实现 接口 的 类 一 一 结构 体 B 的 第 1 个 位 
置 。 这 样 一 个 指向 B 的 指针 ， 也 可 以 强制 转换 类 型 为 A 再 调用 A 的 成 


员 。 如 果 读 者 朋友 觉得 比较 抽象 ， 那 么 u_char*ip 指 问 
ngx_http_script_code_pt 函 数 指针 融 是 一 个 非 癌 好 的 例子 。 


首先 ，ngx_http_script_code_pt 是 一 个 函数 指针 ， 当 然 它 即使 是 一 
个 结构 体 也 无 所 谓 。 看 看 它 的 定义 : 


typedef void (*ngx_http_script_code_pt) (ngx_http_script_engine_t *e); 


ngx_http_script_code_pt 的 唯一 参数 驶 是 脚本 引擎 
ngx_http_script_engine_t， 它 表示 了 当前 指令 的 脚本 上 下 文 。 


ngx_http_script_code_pt 相 当 于 抽象 基 类 的 一 个 接口 ， 所 以 会 有 相 
应 的 结构 体 担当 类 的 角色 。 对 于 “set" 配 置 来 说 ， 编 译 变量 名 〈 即 第 1 个 
参数 ) 由 一 个 实现 了 ngx_http_script_code_pt 接 口 的 类 担当 ， 这 个 类 实 
际 上 是 由 结构 体 ngx_http_script_var_code _t 来 承担 的 ， 如 下 所 示 : 


typedef struct { 
// 在 本 节 的 例子 中 ， 


code 指 向 的 脚本 指令 方法 为 


ngx_http_script_set_var_code 
ngx http script_code_pt code; 
// 表示 


ngx_http_request_t 中 被 索引 、 缓 存 的 变量 值 数组 


variables 中 ， 当 前 解析 的 、 


// set 设 置 的 外 部 变量 所 在 的 索引 号 


uintptr_t index; 
} ngx_http_script_var_code_t; 


我 们 可 以 注意 到 ， 第 1 个 成 员 就 是 ngx_http_script code_pt code， 这 
意味 着 可 以 把 ngx_http_script_var_code_t 强 转 为 ngx_http_script_code_pt 
方法 执行 。 


看 到 了 uintptr_ t 类 型 的 index 成 员 ， 大 家 可 能 又 会 想 ， 又 要 “多 用 
途 ” 了 吗 ? 既 作 普通 整 型 又 做 指针 ? 这 里 纯粹 只 是 Nginx 的 习惯 而 已 ， 
index 成 员 只 用 来 做 表示 索引 号 的 整 型 ， 用 于 与 ngx_http_request_t 请 求 
中 索引 化 的 variables 变 量 值 配合 工作 。 这 里 我 们 已 经 看 到 ，set 定 义 的 外 
部 变量 只 能 作为 索引 变量 使 用 (不 能 作为 hash 变 量 使 用 ) 。 


set 的 第 2 个 参数 是 变量 值 ， 它 也 需要 一 个 新 的 结构 体 
ngx_http_script_value_code t 来 编译 ， 看 看 它 的 定义 : 


typedef struct { 
// 在 本 节 的 例子 中 ， 


code 指 向 的 脚本 指令 方法 为 


ngx_http_script_value J 
ngx_http script code_p code; 


// 若 外 部 变量 值 是 整数 ， 疯 对 为 玫 型 写 民 和 


value， 否 则 

value 为 

0 
uintptr_t value; 
// 外 部 变量 值 ( 

set 的 第 

2 个 参数 ) 的 长 度 


uintptr_t text_len; 
// 外 部 变量 值 的 起 始 地 址 


uintptr_t text_data; 
} ngx_http_script_value code _t; 


对 于 ngx_http_script_code_pt 方 法 的 实现 我 们 在 15.4.3 节 再 解释 。 那 
么 为 什么 一 行 set 脚 本 要 分 别 由 编译 变量 名 、 编 译 变量 值 的 2 个 结构 体 来 
表示 呢 ? 因 为 set 有 很 多 不 同 的 使 用 场景 ， 对 变量 名 来 说 ， 束 存在 变量 
名 百 次 出 现 与 非 首 次 出 现 ， 而 变量 值 承 有 纯 字 符 串 、 字 符 串 与 其 他 变 
量 的 组 合 等 情况 。 把 变量 名 的 编译 提取 为 ngx_http_script_var_code_t 结 
构 体 ， 使 所 有 变量 名 的 编译 可 以 复 用 其 index 成 员 ， 而 具体 的 
ngx_http_script_code_pt 指 令 执 行 则 可 以 各 目 实 现 ， 把 变量 值 的 编译 提 
取 为 ngx_http_script_value_code_t 结 构 体 则 可 以 复 用 text_len 、text_data 


忆 
II 


ngx_http_script_engine_t 是 随 着 HTTP 请 求 到 来 时 才 创 建 的 ， 所 以 它 
无 法 保存 Nginx 启 动 时 就 编译 出 的 脚本 。 你 存 编译 后 的 脚本 这 个 工作 实 
际 上 是 由 ngx_http_rewrite_loc_conf t 结 构 体 承 担 的 ， 如 下 所 示 : 


typedef struct { 
// 保存 着 所 属 


location 下 的 所 有 编译 后 的 脚本 (按照 顺序 ) 


1 


ngx_array_t *codes; 
// 每 一 个 请 求 的 


ngx_http_script_engine_t 脚 本 引擎 中 都 会 有 一 个 变量 值 栈 ， 


// 即 上 面 提 到 的 


ngx_http_variable_value_t *sp， 它 的 大 小 就 是 


stack_size 
ngx_uint_t stack_size,; 
} ngx_http_rewrite_ loc conf_t; 


从 名 称 就 可 以 看 出 ，ngx_http_rewrite_ loc_conf_ t 其 实 就 是 
ngx_http_rewrite _ module 模块 在 location 级 别 的 配置 结构 体 ， 即 每 一 个 
location 下 都 会 有 1 个 ngx_http_rewrite_loc_conf t 结 构 体 。 如 果 这 个 
location 下 没有 脚本 式 配置 ， 那 么 其 成 员 codes 数 组 融 是 空 的， 否则 codes 
数组 束 会 放置 承载 着 补 解 析 后 的 脚本 指令 的 结构 体 。 


成 员 codes 数 组 的 设计 是 比较 独特 的 。 前 文 我 们 说 过 ， 脚 本 指令 都 
是 实现 了 “接口 ngx_http_script_code_pt” 的 各 个 不 同 的 充当 “类 ”的 结构 
体 ， 这 些 结构 体 可 以 是 ngx_http_script_var_code_t、 
ngx_http_script_value_code_t 等 ， 它 们 的 类 型 不 同 ， 占 用 的 内 存 也 不 
同 ， 如 何 把 它们 整个 放 入 1 个 数组 中 呢 (注意 : 不 是 把 它们 的 指针 放 到 
数组 中 ! ) ? 以 下 3 扩 束 可 以 做 到 : 


1) codes 数 组 设计 成 每 个 元 素 仅 占 1 个 字 市 的 大 小 ， 也 就 是 说 ， 我 
们 不 奢望 一 个 数组 元 素 束 能 存放 表示 1 个 脚本 指令 的 结构 体 。 


2) 每 次 要 将 1 个 指令 放 入 codes 数 组 中 时 ， 将 根据 指令 结构 体 的 占 
用 内 存 字 世 数 N， 在 codes 数 组 中 分 配 N 个 元 素 存 储 这 1 个 指令 ， 再 依次 
把 指令 结构 体 的 内 容 都 拷贝 到 这 N 个 数组 成 员 中 。 如 下 所 示 : 


void * 
ngx_http_script_start_code(ngx_pool t *pool, ngx_array _t **codes, size t size) 


if (*codes == NULL) { 
// codes 数 组 的 每 


1 个 元 素 内 


As 


个 季 人 也 


*codes = ngx_array_create(pool, 256, 1); 
If (*codes == NULL) { 
return NULL; 
} 
} 
17 这 


size 就 是 类 似 


ngx_http_script_value_code_t 表 示 脚 本 指令 的 结构 体 所 占用 的 内 存 字 节 数 ， 


/AY 流 个 


ngx_array_push_n 就 会 直接 创建 
size 个 数组 元 素 ， 仅 用 来 存储 


1 个 表示 指令 的 结构 体 


return ngx_array_push_n(*codes, size); 


3) HTTP 请 求 到 来 、 脚 本 指令 执行 时 ， 每 执行 完 一 个 脚本 指令 的 
ngx_http_script_code_pt 方 法 后 ， 该 方法 必须 主动 地 告知 所 属 指 令 结构 
体 占 用 的 内 存 数 N， 这 样 从 当前 指令 所 在 的 codes 数 组 索引 中 加 上 NN 后 就 


是 下 一 条 指令 。 


这 样 我 们 就 把 实现 外 部 变量 的 关键 结构 体 都 介绍 了 ， 再 以 图 15-6 来 
形象 地 表示 内 存 中 它们 之 间 的 关系 。 


图 15-6 以 “set$variable value;” 配 置 项 作为 示例 ， 两 个 HTTP 请 求 (A 
和 B) 同时 执行 到 该 行 脚本 ， 其 中 ，A 请 求 正 准备 执行 值 value 的 指令 
ngx_http_script_value_code_t， 而 B 请 求 已 经 执行 完 值 的 入 栈 ， 正 要 执行 


指令 ngx_http_script_var_code_t。ngx_http_script_engine_t 脚 本 引擎 的 sp 


成 员 始 终 指 癌变 量 值 栈 里 正 要 操作 的 值 ， 而 ip 成 员 则 始终 指向 将 要 执行 
的 下 一 条 指令 结构 体 。 


15.4.2 ”编译 “set” 脚 本 


仍然 以 set 为 例 看 看 脚本 配置 是 如 何在 Nginx 的 启动 过 程 中 编译 的 。 
当 发 现 “set$variable value:” 配 置 时 ， 其 编译 流程 (处 理 set 配 置 的 
ngx_http_rewrite_set 方 法 ) 如 图 15-7 所 示 。 


详细 介绍 一 下 图 15-7 的 各 个 步骤 : 


1) 首先 验证 set 后 续 参 数 的 合法 性 ， 例 如 第 1 个 参数 必须 是 以 $ 符 号 
开始 的 变量 名 。 


2) 在 15.2.3 节 我 们 介绍 过 定义 内 部 变量 的 ngx_http_add_variable 方 
法 ， 添 加 外 部 变量 一 样 是 调用 这 个 方法 。 需 要 注意 的 是 ， 外 部 变量 是 
允许 重复 定义 的 ， 即 可 以 先 执行 set$variable valuel 再 执行 set$variable 
value2， 这 样 当 后 者 调用 ngx_http_add_variable 方 法 时 ， 返 回 的 
ngx_http_script_var_code_t 结 构 体 其 实 是 前 者 已 经 定义 好 的 。 所 以 对 于 
外 部 变量 而 言 ，ngx_http_add_variable 方 法 传 入 的 flags 必 须 含 有 


NGX HTTP VAR CHANGEABLE 标 志 位 (参见 表 15-2) 。 


ngx_http_script_engine tt 


ip: 待 执行 指令 


间 癌 HTTP 请 求 


ngx_http_variable_value_t 型 量 值 构成 的 请 求 A 数 据 栈 ， 变 量 值 解 析 时 快速 入 栈 ， 变 量 解析 时 即 出 栈 


request: 指向 HTTP 请 求 


pp 


请 求 B 一 
ngx_h variahle_value_t 变 量 值 构成 的 请 求 B 数 据 栈 
压 栈 人 pr = 
py code: 执行 变量 值 压 栈 
/ 
区 
执行 到 哪 就 指 人 pa value: 值 为 整 型 时 存 整数 
六 
出 栈 ” / 
/ 
/ 
> / 
本 code: 执行 值 出 栈 并 设置 
ze 月 区 Index: 变量 variable 索 引号 
感 pa 
ps ‘ 1 
/ 7 hy 
,” ， 先 解 析 变 量 值 p44 再 解析 变量 | 名 
人 
[aaa ja 
/ a 
， location 下 所 有 脚本 语句 构成 前 
| ngx_http_seript_XXXZeode_( 数 组 
codes: 脚本 语句 数组 = ll 


stack_size: 指定 栈 长 度 
ee 


图 15-6 ”外 部 变量 实现 的 各 数据 结构 间 的 内 存 关 系 示 意图 


图 中 以 “set$variable value;” 作 为 示例 ， 脚 本 由 右 辐 左 解析 为 


ngx_http_script_value_code t、 ngx_http_script_var_ code t 


1 ) 验证 set 第 1 个 参数 必须 是 $ 开 头 的 变量 


2 ) 调用 ngx_http_add_variable 方 法 添加 这 个 外 部 变量 


3 ) 调用 ngx_http_get_variable_index 方 法 将 变量 索引 化 处 理 


4 ) 若 变 量 定义 的 get_handler 未 设置 过 ， 是 不 为 5 类 特殊 变量 ， 重 设 get_handler 防 止 出 错 


5 ) 设置 第 2 个 值 参数 的 脚本 处 理 方法 


5.1 ) 检查 参数 中 是 否 还 有 $ 打 头 的 变量 


[变量 值 中 不 再 含有 变量 ] 


[变量 值 含有 其 他 变量 ] 


5.2 ) 设置 处 理 字符 串 值 的 指令 ngx_http_script_value_code_t 


5.3 ) 设置 ngx_http_script_complex_value_code_t 处 理 含有 变量 的 值 


6 ) 检查 该 变量 是 否定 义 过 的 内 部 变量 、 有 日 set_handler 方 法 设置 过 


[变量 被 定义 过 、set_handler 也 设置 过 ] 


< 


[set_handler 为 NULL 空 指针 ] 


7) 设置 变量 名 脚本 语句 的 处 理 方法 ngx_http_script_var_code t 


8 ) 设置 处 理 该 变量 的 方法 为 ngx_http_script_var_handler_code t 


图 15-7 编译 set 脚 本 配置 的 流程 


3) 前 文 我 们 说 过 ， 变 量 是 分 为 定义 和 使 用 两 部 分 的 ， 唯 有 打算 使 
用 它 时 才 应 该 索引 化 ， 把 它 的 值 缓存 到 请 求 的 variables 数 组 中 。 而 对 
ngx_http_rewrite_ module 模 块 的 外 部 变量 而 言 ，set 配 置 既定 义 了 一 个 变 
量 ， 也 表明 会 使 用 这 个 变量 。 所 以 一 定 会 调用 
ngx_http_get_variable_index 方 法 把 变量 索引 化 的 ， 同 时 索引 值 会 保存 到 
ngx_http_script_var_code _t 结 构 体 的 index 成 员 里 (参见 15.4.1 节 ) 


4) 内 部 变量 的 get_handler 方 法 是 必须 实现 的 ， 因 为 通常 都 是 采 
用 “惰性 求 值 >， 即 只 有 读 取 这 个 变量 值 时 才 会 去 调用 get_handler 计 算出 
这 个 值 。 然 而 外 部 变量 是 不 同 的 ， 每 一 次 set 都 会 立刻 给 变量 重新 赋 
值 ， 同 时 读 取 变量 值 时 ， 因 为 变量 值 是 被 索引 化 的 ， 所 以 可 以 直接 从 
请 求 的 variables 数 组 里 取 到 set 后 的 值 。 这 样 get_handler 似 乎 是 没有 用 武 
之 地 的 。 然 而 ， 可 能 有 些 模块 会 在 set 脚 本 执行 之 前 就 使 用 到 外 部 变量 
了 ， 此 时 外 部 变量 的 值 是 不 存在 的 ， 即 缓存 的 variables 数 组 里 变量 值 是 
空 的 。 从 15.2 节 可 知 ， 此 时 会 调用 get_handler 方 法 来 读 取 变 量 值 ， 所 以 
外 部 变量 的 get_handler 方 法 也 不 可 以 为 NULL， 它 被 定义 为 
ngx_http_rewrite_var 方 法 ， 这 个 方法 所 做 的 唯一 工作 就 是 把 变量 值 置 为 


ngx_http_variable_null_value 空 值 : 


ngx_http_variable value t ngx_http_variable _ null_ value = 
ngx_http_variable(""); 


当 第 2 步 添加 变量 时 获得 的 ngx_http_variable_t 中 get_handler 为 
NULLH 上 时， 如果 变量 名 的 前 缀 属于 5 类 特殊 变量 (参见 表 15-1) ， 那 么 
在 所 有 配置 项 解析 完毕 后 (当然 也 包括 脚本 式 配 置 set) ， 在 图 15-1 的 
第 5.2 步 骤 中 职 会 给 这 类 变量 重新 设置 get_handler 方 法 。 所 以 对 于 非 5 类 
特殊 变量 且 get_handler 为 NULL 时 ， 就 得 把 get_handler 设 置 为 
ngx_http_rewrite_var 方 法 ， 使 得 外 部 变量 未 赋值 时 读 取 它 可 以 获得 空 
值 。 


5) 开始 处 理 set 的 第 2 个 值 参数 ( 即 调用 ngx_http_rewrite_value 方 法 
处 理 ) 


5.1) 这 个 参数 可 以 是 纯 字符 串 ， 也 可 以 含有 其 他 变量 ， 这 二 者 之 
间 的 处 理 方式 是 不 同 的 。 所 以 首先 检查 这 第 2 个 值 参数 里 有 没有 $ 符 
号 ， 知 像 本 节 的 例子 set$variable value 中 值 中 是 没有 变量 的 ， 则 跳 到 5.2 
执行 ， 否 则 执行 5.3 步 又。 


5.2) 到 这 里 我 们 已 经 可 以 开始 编译 纯 字符 串 的 变量 值 了 。 束 像 上 
一 方 介绍 的 那样 ， 纯 字符 串 值 的 指令 结构 体 是 
ngx_http_script_value_code_t， 我 们 下 先 会 把 它 添加 到 所 在 location 下 的 
ngx_http_rewrite_loc_conf_t 配 置 结构 体 的 codes 数 组 中 ， 如 下 : 


ngx_http_script_value code t *val; 
val = ngx_http_script_start_ code(cf->pool, &]lcf->codes, 
sizeof (ngx_http_script_value_ code_t)); 


接着 ， 如 同 15.4.1 广 介绍 过 的 那样 ， 将 ngx_http_script_value_code_t 
的 4 个 成 员 赋 值 : 


n = ngx_atoi(value->data, value->len); 
if (n == NGX_ERROR) { 
n = 0; 


val->code = ngx_http_script_value_code; 
val->value = (uintptr_t) n; 

val->text_len = (uintptr_t) value->len; 
val->text_data = (uintptr_t) value->data; 


实际 执行 脚本 指令 的 ngx_http_script_value_code 方 法 在 下 一 节 介 


5.3) 如 果 值 参数 中 含有 其 他 变量 ， 那 么 处 理 方式 会 复杂 一 些 。 此 
时 ngx_http_script_complex_value_code_t 会 作为 指令 结构 体 添 加 到 codes 
数组 中 。 本 章 不 对 此 做 详细 介绍 。 


6) 把 变量 值 编译 好 后 ， 再 来 编译 变量 名 。 如 果 set 的 变量 其 实 是 
个 定义 过 的 内 部 变量 ， 那 么 第 2 步 返 回 的 就 是 被 某 个 Nginx 模 块 定义 过 
的 ngx_http_variable_t， 它 的 set_handler 很 可 能 设置 过 。 如 果 set_handler 
设置 过 则 执行 第 8 步 ， 否 则 执行 第 7 步 。 


7) 大 部 分 情况 下 ， 内 部 变量 不 会 与 外 部 变量 混合 在 一 起 使 用 。 此 
时 ， 我 们 首先 把 ngx_http_script_var_code_t 指 令 结 构 体 添加 到 codes 数 组 
中 ， 再 把 变量 的 索引 号 传 到 index 成 员 ， 并 设置 变量 指定 的 执行 方法 为 
ngx_http_script_set_var_code 〈 下 一 节 再 介绍 其 实现 ) ， 如 下 所 示 : 


vcode->code = ngx_http_script_set_Vvar_code 
vcode->index = (uintptr t) index; 


8) 如 果 一 个 内 部 变量 希望 在 nginx.conf 文 件 中 用 set 命 令 修改 其 
值 ， 那 么 它 就 会 实现 set_handler 方 法 ， 意 思 是 ， 执 行 到 set 指 令 时 ， 解 析 
变量 值 时 请 调用 这 个 set_handler 方 法 吧 。 如 何 实现 这 一 意图 呢 ? 新 增 一 
个 ngx_http_script_var_handler_code_t 指 令 结构 体 ， 专 门 处 理 这 种 “内 外 


混用 ”的 变量 : 


typedef struct { 


ngx_http_script_code_pt code; 
ngx_http_set_variable_pt handler; 
uintptr_t data,; 


} ngx_http_script_var_handler_code_t; 


可 以 看 到 它 并 没有 index 成 员 ， 为 什么 呢 ? 因为 set_handler 方 法 是 由 
内 部 变量 定义 过 的 ， 这 个 方法 肯定 能 够 找到 变量 值 (不 需要 关心 它 是 
口 


人 否 通过 索引 下 标 ) 。 


当 执行 到 set 脚 本 指令 设置 这 个 变量 的 值 时 ， 就 调用 set_handler 方 法 
( 即 上 面 的 handler 回 调 方法 ) 处 理 。 


这 一 步 又 就 是 将 ngx_http_script_var_handler_code_t 指 令 结 构 体 添加 


到 codes 数 组 中 ， 并 正确 给 其 各 成 员 赋值 : 


ngx_http_script_var_handler_code t *vhcode; 

vhcode = ngx_http_script_start_ code(cf->pool, &lcf->codes, 
sizeof(ngx_http_script_var_handler_code_ t)); 

vhcode->code = ngx_http_script_var_set_handler_code; 

vhcode->handler = v->set_handler,; 

vhcode->data = v->data; 


它 的 data 成 员 束 被 赋值 为 set 第 2 个 参数 变量 值 ，handler 方 法 则 为 内 
部 变量 已 经 定义 过 的 set_ handler 方 法 ， 而 code 执 行 指令 方法 则 为 


ngX_http_script_var_set_handler_code， 下 一 节 我 们 会 详细 介绍 。 


15.4.3 ”脚本 执行 流程 


当 HTTP 请 求 执行 到 NGX_HTTP_SERVER_REWRITE_PHASE 或 者 
NGX_HTTP_REWRITE_PHASE 阶 段 时 ， 束 有 可 能 执行 脚本 〈 前 提 是 加 
入 了 ngx_http_rewrite_ module 模 块 ， 日 nginx.conf 里 有 该 模块 提供 的 脚本 
式 配置 ) 。 图 15-8 展 示 了 执行 脚本 的 ngx_http_rewrite_handler 方 法 主要 
流程 。 


1 ) 获取 请 求 所 属 location 下 的 配置 ngx_http_rewrite_loc_conf t 
[location 下 是 否 存 在 待 执行 脚本 ? ] 


2 ) 为 当前 请 求 构建 脚本 引擎 ngx_http_script_engine tt 


3 ) 构建 脚本 引擎 的 数据 栈 sp 


5 ) 执行 脚本 对 应 的 ngx_http_script_code_pt 方 法 


图 15-8 ”执行 脚本 的 流程 


下 面 将 会 介绍 图 15-8 的 各 步骤 ， 同 时 也 将 介绍 图 15-7 中 第 5.2、7、 
8 步 中 编译 后 的 指令 : 


1) 首先 获取 location 所 属 的 ngx_http_rewrite_loc_conf t 结 构 体 ， 因 
为 所 有 的 脚本 指令 都 保存 在 它 的 codes 数 组 中 ， 所 以 检查 codes 数 组 是 否 
为 NULL 就 可 以 知道 ， 当 前 location 下 是 否 有 脚本 配置 存在 。 若 没有 肢 
本 ， 则 ngx_http_rewrite_module 方 法 可 以 直接 结束 。 


2) 执行 脚本 前 ， 一 定 要 先 建立 一 个 脚本 引擎 
ngx_http_script_engine_t， 这 个 结构 体 只 为 这 个 请 求 、 这 个 location 服 


务 。 如 下 : 


ngx http_script_engine_t 
e = ngx_pcalloc(r->pool, 全 人 http_script_engine_t)); 


3) 建立 变量 值 构成 的 栈 ， 如 下 所 示 : 


ngx_http_rewrite loc conf_t *rlcf; 
rlcf = ngx_http_get_module_loc conf(r, ngx_http_rewrite module); 
e->sp = ngx_pcalloc(r->pool, 

rlcf->stack_size * sizeof(ngx_http_variable value_ t)); 


4) 所 有 的 脚本 指令 都 在 tcf->codes 数 组 中 ， 虽 然 每 个 指令 结构 体 
大 小 不 一 致 ， 但 有 两 点 可 以 确定 : 数组 的 第 1 个 成 员 就 古 第 1 个 指令 结 
构 体 ， 每 个 指令 结构 体 的 第 1 个 成 员 一 定 是 ngx_http_script_code_pt 芳 数 
指针 ， 所 以 可 以 先 把 ip 指 疝 数 组 自 地 址 ， 并 把 ip 强 制 转化 为 


ngx_http_script_code_pt 方 法 执行 脚本 ， 其 中 每 一 个 方法 负责 把 ip 移 向 下 
一 条 待 执 行 的 脚本 指令 ， 如 下 : 


// codes 数 组 第 

1 个 元 素 就 是 第 

1 个 指令 结构 体 

e->ip = rlcf->codes->elts; 
// ip 指 向 


NULL 时 就 说 明 脚本 执行 完毕 


while (*(uintptr_t *) e->ip) { 
每 


1 个 指令 结构 体 的 第 


1 个 成 员 一 定 是 


ngx_http_script_code_pt 方 法 


code = *(ngx_http_script_code pt *) e->ip; 
// 执行 指令 方法 时 ， 该 方法 负责 移动 


ip 指 针 


code(e); 


5) 现在 我 们 可 以 详细 看 看 每 条 脚本 指令 执行 时 到 底 是 如 何 工作 
的 。 图 15-7 中 人 第 5.2 步 里 编译 了 一 条 执行 纯 字 符 串 值 的 脚本 指令 结构 
体 ， 它 在 上 面 的 code(e) 执 行 时 方法 为 ngx_http_script_value_code， 看 看 
到 展 做 了 又 休会: 


void 
ngx_http_script_value code(ngx_http_script_engine t *e) 


ngx_http_script_value code t *code; 
// 由 于 


ngx_http_script_code_pt 是 指令 结构 体 的 第 


1 个 成 员 ， 所 以 
ip 同 时 也 指向 了 指令 结构 体 。 


// 对 于 编译 纯 字符 串 变 量 值 而 言 ， 其 指令 结构 体 为 


ngx_http_script_value_code_t， 这 样 ， 


// 就 从 


codes 数 组 中 取 到 了 指令 结构 体 
code 
code = (ngx_http_script_value_code_ t *) e->ip; 


// 为 了 能 够 执行 下 一 条 脚本 指令 ， 先 提 
ip 移 到 下 一 个 指令 结构 体 的 地 址 上 。 移 动 方式 很 简单 ， 


[ 旦 


// 右 移 


sizeof(ngx_http_script_value_code 七 ) 字 节 即 可 


e->ip += sizeof(ngx_http_script_value_ code t); 


// e->sp 指 向 了 栈 顶 元 素 ， 处 理 脚 本 变量 值 时 ， 先 把 这 个 值 赋 给 栈 顶 元 素 


e->sp->len = code->text_len; 
e->sp->data = (u_char *) code->text_ data; 


// 栈 自动 上 移 


e->Sp++; 


当 变 量 是 普通 的 外 部 变量 时 ， 图 15-7 中 第 7 步 设置 了 变量 名 的 指令 
执行 方法 为 ngx_http_script_set_var_code， 看 看 它 是 如 何 与 变量 值 栈 配 
合 的 : 


void 
ngx_http_script_set var_code(ngx_http_script_ engine t *e) 


ngx_http_request_t 不 这 
ngx_http_script _ var_code t *code; 


// 同样 由 指向 


ngx_http_script_set_var_code 方 法 的 指针 


ip 可 以 获取 到 
ngx_http_script_ 
// var_code_t 指 令 结构 体 
code = (ngx_http_script _ var_code t *) e->ip; 


// 将 


ip 移 到 下 一 个 待 执行 脚本 指令 


e->ip += sizeof(ngx_http_script_var_code t); 
r = e->request,; 


// 首先 把 栈 下 移 ， 指 向 


ngx_http_script_value_code 设 置 的 那个 纯 字 符 串 的 变量 值 


e->sp--; 


// 根据 


ngx_http_script_var_code_t 的 


index 成 员 ， 可 以 获得 被 索引 的 变量 


桓 


// r->variables[code->index], 以 下 


5 行 语句 就 是 


e->sp 栈 里 的 字符 串 来 设置 这 个 变量 值 


r->variables[code->index].len = e->sp->len; 
r->variables[code->index] .valid = 1; 
r->variables[code->index].no_cacheable = 0; 
r->variables[code->index].not_found = 0; 
r->variables[code->index].data = e->sp->data,; 


如 果 set 的 变量 是 像 args 这 样 的 内 部 变量 ， 它 的 处 理 方法 义 有 不 同 。 
因为 args 变 量 的 set_handler 方 法 不 为 NULL， 看 看 它 的 定义 : 


static ngx_http_variable t ngx_http_core variables[] = { 
{ ngx_string("args"), 
// set_handler 方 法 不 是 


NULL 
ngx_http_variable_request_set, 
ngx_http_variable_request, 
offsetof(ngx_http_request_t, args), 
// 人 允许 


set 脚 本 来 重新 设置 这 个 


args 变 量 ， 所 以 必须 使 


flags 标 志 位 具有 


NGX_HTTP_VAR_CHANGEABLE 
NGX_HTTP_VAR_CHANGEABLE|NGX_HTTP_VAR_NOCACHEABLE，9 }, 


在 图 15-7 的 第 8 步 中 ， 对 于 设置 了 set_handler 的 变量 ， 它 的 脚本 指 
令 执 行 方 法 为 ngx_http_script_var_set_handler_code， 看 看 它 的 实现 : 


void 
ngx_http_script_var_set_handler_code(ngx_http_script_engine _t *e) 


ngx_http_script_var_handler_code t *code; 
// 同样 获取 到 指令 结构 体 


code = (ngx_http_script_var_handler_ code t *) e->ip; 
// 移动 


ip 到 下 一 条 待 执行 指令 


e->ip += sizeof(ngx_http_script var_handler_code_t); 


// 变量 值 栈 移动 


e->Sp--; 
// 将 请 求 、 变 量 值 传递 给 


set_handler 方 法 执行 它 


code->handler(e->request, e->sp, code->data); 


所 有 的 脚本 指令 执行 时 都 与 上 面 3 个 例子 相似 ， 读 者 朋友 可 以 通过 
阅读 源 代码 掌握 ngx_http_rewrite_module 模 块 的 更 多 脚本 实现 原理 。 


15.5 ”小 结 


本 章 由 浅 入 深 地 先 从 如 何 使 用 内 部 变量 说 起 ， 进 而 分 析 了 内 部 变 
量 的 工作 原理 ， 包 括 定 义 、 使 用 时 各 部 分 是 如 何 配合 使 用 的 ， 再 以 一 
个 例子 说 明 如 何 定义 新 的 内 部 变量 (未 使 用 的 艇 入 式 变量 ) 。 


外 部 变量 是 由 ngx_http_rewrite_module 模 块 引 入 的 ， 本 章 后 半 部 分 
说 明了 该 模块 的 脚本 引擎 是 如 何 实现 外 部 变量 的 ， 包 括 脚本 在 Nginx 启 
动 时 的 编译 与 HTTP 请 求 到 来 时 的 执行 ， 并 分 析 了 内 部 变量 如 何 与 外 部 


变量 混合 着 使 用 。 


读者 朋友 通过 阅读 本 章 ， 可 以 在 开发 HTTP 模块 时 很 轻松 地 使 用 
HTTP 变 量 ， 甚 至 可 以 通过 对 比 ngx_http_rewrite_module 模 块 的 实现 ， 
在 自己 的 模块 中 开发 新 的 脚本 引擎 。 


第 16 章 ”slab 共 享 内 存 


许多 场景 下 ， 不 同 的 Nginx 请 求 间 必 须 交 互 后 才能 执行 下 去 ， 例 如 
限制 一 个 客户 端 能 够 并 发 访问 的 请 求 数 。 可 是 Nginx 被 设计 为 一 个 多 进 
程 的 程序 ， 服 务 更 健壮 的 另 一 面 就 是 ，Nginx 请 求 可 能 是 分 布 在 不 同 的 
进程 上 的 ， 当 进程 间 需 要 互相 配合 才能 完成 请 求 的 处 理 时 ， 进 程 间 通 
信 开 发 困难 的 特点 就 会 凸显 出 来 。 第 14 章 介绍 过 一 些 进程 间 的 交互 方 
法 ， 例 如 14.2 节 的 共享 内 存 。 然 而 如 果 进 程 间 需要 交互 各 种 不 同 大 小 
的 对 象 ， 需 要 共享 一 些 复杂 的 数据 结构 ， 如 链表 、 树 、 图 等 ， 那 么 这 
些 内 容 将 很 难 支 撑 这 样 复杂 的 语义 。Nginx 在 14.2 节 共享 内 存 的 基础 
上 上， 实现 了 一 套 高 效 的 slab 内 存 管理 机 制 ， 可 以 帮助 我 们 快速 实现 多 
种 对 象 间 的 跨 Nginx worker 进 程 通信 。 本 章 除 了 说 明 如 何 使 用 它 以 
外 ， 同 时 还 会 详细 介绍 实现 原理 ， 从 中 我 们 可 以 发 现 它 的 设计 初 囊 及 
不 适用 的 场景 。Slab 实 现 的 源 代码 非常 高 效 ， 然 而 却 也 有 些 生 涩 ， 本 
章 会 较 多 地 通过 源 代码 说 明 各 种 二 进 制 位 操作 ， 以 帮助 读者 朋友 学 习 
slab 的 编码 艺术 。 


16.1 操作 slab 共 享 内 存 的 方法 


操作 slab 内 存 池 的 方法 只 有 下 面 5 个 : 


// 初始 化 新 创建 的 共享 内 存 


void ngx_slab_init(ngx_slab_pool _t *pool); 
// 加 锁 保护 的 内 存 分 配方 法 


void *ngx_slab alloc(ngx_slab_ pool t *pool, size t size); 
// 不 加 锁 保 护 的 内 存 分 配方 法 


void *ngx_slab_alloc locked(ngx_slab pool t *pool, size t size); 


// 加 锁 保护 的 内 存 释放 方法 


void ngx_slab_free(ngx_slab pool t *pool, void *p); 
// 不 加 锁 保 护 的 内 存 释 放 方 法 


void ngx_slab_ free locked(ngx_slab pool t *pool, void *p); 


这 5 个 方法 是 src/core/ngx_slab.h 里 仅 有 的 5 个 方法 ， 其 精简 程度 可 
见 一 班 。ngx_slab_init 由 Nginx 框 架 自 动 调用 ， 使 用 slab 内 存 池 时 不 需 
要 关注 它 。 通 常 要 用 到 slab 的 都 是 要 跨 进程 通信 的 场景 ， 所 以 
ngx_slab_alloc_locked 和 ngx_slab_free_locked 这 对 不 加 锁 的 分 配 、 释 放 
内 存 方法 较 少 使 用 ， 除 非 模块 中 已 经 有 其 他 的 同步 锁 可 以 复 用 。 
此 ， 模 块 开 发 时 分 配 内 存 调 用 ngx_slab_alloc， 参 数 size 就 是 需要 分 配 
的 内 存 大 小 ， 返 回 值 就 是 内 存 块 的 首 地 址 ， 共 享 内 存 用 尽 时 这 个 方法 
会 返回 NULL; 释放 这 块 内 存 时 调用 ngx_slab_free， 参 数 p 就 是 


ngx_slab_alloc 返 回 的 内 存 地 址 。 还 有 一 个 参数 ngx_slab_pool_t*pool 又 
是 怎么 来 的 呢 ? 


很 简单 ， 由 下 面 的 ngx_shared_memory_add 方 法 即 可 拿 到 必须 的 


ngx_slab_pool_t*pool 参 数 : 


// 告诉 
Nginx 初 始 化 
1 块 大 小 为 
size、 名 称 为 


name 的 


slLab 共 享 内 存 池 


ngx_shm_zone_t *ngx_shared_memory_add(ngx_conf t *cf, ngx_str_t *name, size_t 
size, void *tag); 


ngx_shared_memory_add 和 需要 4 个 参数 ， 从 第 1 个 参数 ngx_conf _t*cf 
的 配置 文件 结构 体 就 可 以 推测 出 ， 该 方法 必须 在 解析 配置 文件 这 一 步 
中 执行 。 所 以 在 ngx_command t 里 定义 的 配置 项 解析 方法 中 可 以 拿 到 
ngx_conf txcf， 通 常 ， 我 们 都 会 在 配置 文件 里 设置 共享 内 存 的 大 小 。 
当然 ， 各 http 模 块 都 是 在 解析 http{} 配 置 项 时 才 会 被 初始 化 ， 定 义 http 
模块 时 ngx_http_module_t 的 8 个 回调 方法 里 也 可 以 拿 到 ngx_conf_ txcf。 


参数 ngx_str_t*name 是 这 块 slab 共 享 内 存 池 的 名 字 。 显 而 易 见 ， 
Nginx 进 程 中 可 能 会 有 许多 个 slab 内 存 池 ， 而 且 ， 有 可 能 多 处 代码 使 用 


同一 块 slab 内 存 池 ， 这 样 才 有 必要 用 唯一 的 名 字 来 标识 每 一 个 slab 内 存 
池 。 


参数 size_t Size 设置 了 共享 内 存 的 大 小 。 


参数 void*tag 则 用 于 防止 两 个 不 相关 的 Nginx 模 块 所 定义 的 内 存 池 
恰好 具有 同样 的 名 字 ， 从 而 造成 数据 错乱 。 所 以 ， 通 党 可 以 把 tag 参 数 
传 入 本 模块 结构 体 的 地 址 。tag 参 数 会 存放 在 ngx_shm_zone_t 的 tag 成 员 
中 。 


人 @@ 注音 。 当 我 们 执行 -s reload 命 令 时 ，Nginx 会 重新 加 载 配置 广 
件 ， 此 时 ， 会 触发 再 次 初始 化 slab 共 享 内存 池 。 而 在 该 过 程 中 ，tag 地 
址 同样 将 用 于 区 分 先后 两 次 的 初始 化 是 否 对 应 于 同一 块 共享 内 存 。 所 
以 ，tag 中 应 传 入 全 局 变量 的 地 址 ， 以 使 两 次 设置 tag 时 传 入 的 是 相同 地 
址 。 


如 果 前 后 两 次 设置 的 tag 地 址 不 同 ， 则 会 导致 即使 共 圣 内 存 大 小 没 
有 变化 ， 旧 的 共 圣 内 存 也 会 被 释放 挥 ， 然 后 再 重新 分 配 一 块 同样 大 小 \ 
的 共 译 内 存 ， 这 古 没 有 必要 的 。 


ngx_shared_memory_add 的 返回 值 就 是 用 来 拿 到 
ngx_slab_pool_t*pool 的 ， 如 有 果 返 回 NULL 表 示 获 取 共 享 内 存 失败 。 如 
果 参 数 name 已 经 存在 ，ngx_shared_memory_add 会 比较 前 一 次 name 对 
应 的 共享 内 存 size 是 否 与 本 次 size 人 参数 相等 ， 以 及 tag 地 址 是 否 相 等 ， 如 


果 相 等 ， 直 接 返回 上 一 次 的 共享 内 存 对 应 的 ngx_shm_zone tt， 否则 会 
返回 NULL 。ngx_shm_zone t 究 况 是 怎样 帮助 我 们 拿 到 


ngX_slab_pool_t*pool 的 呢 ? 


先 来 看 看 ngx_shared_memory_add 返 回 了 一 个 怎样 的 结构 体 : 


typedef struct ngx_shm zone_s ngx_shm zone_t; 
struct ngx_shm zone_s { 
// 在 真正 创建 好 


slab 共 享 内 存 池 后 ， 就 会 回调 


init 指 向 的 方法 


ngx_shm_zone_init_pt init; 
// 当 


ngx_shm_zone_init_pt 方 法 回调 时 ， 通 常 在 使 
候 ， 


PE 


slLab 内 存 池 的 代码 前 需要 做 一 些 初始 化 工 


// 这 一 工作 可 能 需要 用 到 在 解析 配置 文件 时 就 获取 到 的 一 些 参数 ， 而 


data 主 要 担当 传递 参数 的 职责 


void *data; 
// 描述 共享 内 存 的 结构 体 

ngx_shm_t shm; 
// 对 应 于 


ngx_shared_memory_add 的 


tag 参 数 
void *tag; 
}; 


拿 下 了 ngx_shm_zone_t 结 构 体 后 ，init 成 员 是 必须 要 设置 的 ， 因 为 
Nginx 后 续 创 建 好 slab 内 存 池 后 ， 会 调用 init 指 癌 的 方法 ， 这 是 约定 


好 的 。ngx_shm_zone_init_pt 函 数 指 针 定 义 如 下 : 


typedef ngx_int_t (*ngx_shm zone_init_pt) (ngx_shm_zone_t *zone, void *data); 


我 们 需要 实现 一 个 这 样 的 方法 ， 然 后 赋 给 ngx_shm_zone_t 的 init 函 
数 指针 。 这 个 方法 被 回调 时 ， 其 第 1 个 参数 就 是 
ngx_shared_memory_add 返 回 的 ， 而 且 是 刚刚 设置 过 其 init 函 数 指针 成 
员 的 ngx_shm_zone _t 结 构 体 。 对 于 ngx_shm_zone_init_pt 的 第 2 个 参数 
void*data， 在 理解 它 之 前 允 要 搞 清 楚 Nginx 的 reload 重 载 配置 文 件 流 
程 。 重 新 解析 配置 文件 意味 着 所 有 的 模块 (包括 http 模 块 都 会 重新 
初始 化 ， 然 而 ， 之 前 正 处 于 使 用 中 的 共享 内 存 可 能 是 有 数据 的 、 可 以 
复 用 的 ， 如 果 丢 弃 了 这 些 旧 数据 而 重新 开辟 新 的 共享 内 存 ， 是 会 造成 
严重 错误 的 。 所 以 如 果 处 于 重读 配置 文件 流程 中 ， 会 尽 可 能 地 使 用 旧 
共享 内 存 (如 果 存 在 的 话 ) ， 表 现在 ngx_shm_zone_init_pt 的 第 2 个 参 
数 void*data 上 时 ， 就 意味 着 : 如 果 Nginx 是 首次 启动 ，data 则 为 空 指针 
NULL; 者 是 重读 配置 文件 ， 由 于 配置 项 、http 模 块 的 初始 化 导致 共 襄 
内 存 再 次 创建 ， 那 么 data 就 会 指向 第 一 次 创建 共享 内 存 时 ， 
ngx_shared_memory_add 返 回 的 ngx_shm_zone_t 中 的 data 成 员 。 读 者 朋 
友 在 处 理 data 参 数 时 请 务必 考虑 以 上 场景 ， 考 虑 如 何 使 用 老 的 共享 内 
存 ， 以 避免 不 必要 的 错误 。 


16.2 ”使 用 Slab 共享 内 存 池 的 例子 


假定 这 样 一 个 场景 : 对 于 来 自 于 同一 个 IP 的 请 求 ， 如 果 客 户 剖 访 
问 某 一 个 URL 并 且 获 得 成 功 ， 则 认为 这 次 访问 是 重量 级 的 ， 但 需要 限 
制 过 于 频率 的 访问 。 因 此 ， 设 计 一 个 http 过 滤 模 块 ， 乔 访问 来 目 同一 个 
IP 有 URL 相同 ， 则 每 N 秒 钟 最 多 只 能 成 功 访问 一 次 。 例 如 ， 设 定 10 秒 钟 
内 仅 能 成 切 访 问 1 次 ， 那 么 某 浏 览 右 0 秒 时 访问 /method/access 成 功 ， 在 
第 1 秒针 仍然 收 到 来 自 这 个 IP 的 相同 请 求 ， 将 会 返回 403 拒 绝 访 问 。 直 
到 第 11 秒 ， 这 个 IP 访 问 /method/access 才 会 再 次 成 功 。 


现在 来 实现 这 样 的 模块 。 首 先 ， 产 品级 的 Nginx 一 定 会 有 多 个 
worker 进 程 ， 来 自 同一 个 IP 的 多 次 TCP 连 接 有 可 能 会 进入 不 同 的 worker 
进程 处 理 ， 所 以 需要 用 共享 内 存 来 存放 用 户 的 访问 记录 。 为 了 高 效 地 
查找 、 插 入 、 删 除 访问 记录 ， 可 以 选择 用 Nginx 的 红 黑 树 来 存放 它们 ， 
其 中 关键 字 吏 是 IP+URL 的 字符 串 ， 而 值 则 记录 了 上 次 成 功 访问 的 时 
间 。 这 样 请 求 到 来 时 ， 以 IP+URL 组 成 的 字符 串 为 关键 字 查 询 红 黑 树 ， 
没有 查 到 或 查 到 后 发 现 上 次 访问 的 时 间距 现在 大 于 某 个 闪 值 ， 则 人 允许 
访问 ， 同 时 将 该 键 值 对 插 下 红 黑 树 ; 反之 ， 若 查 到 了 且 上 次 访问 的 时 
间距 现在 小 于 某 个 阀 值 ， 则 拒绝 访问 。 


考虑 到 共享 内 存 的 大 小 有 限 ， 长 期 运行 时 如 果 不 考虑 回收 不 活跃 
的 记录 ， 那 么 一 方面 红 黑 树 会 越发 巨大 从 而 影 啊 效 率 ， 男 一 方面 共 至 


内 存 会 很 快 用 尽 ， 导 致 分 配 不 出 新 的 结 点 。 所 以 ， 所 有 的 结 点 将 通过 
一 个 链表 连接 起 来 ， 其 插入 顺序 按 IP+URL 最 后 一 次 访问 的 时 间 组 织 。 
这 样 可 以 从 链表 的 首部 插入 者 访问 的 记录 ， 从 链表 尾部 取出 最 后 一 行 
记录 ， 从 而 检查 是 否 需 要 淘 状 出 共享 内 存 。 由 于 最 后 一 行 记录 一 定 是 
最 老 的 记录 ， 如 采 它 不 需要 淘汰 ， 也 就 不 需要 继续 所 历 链表 了 ， 因 此 
可 以 提高 执行 效率 。 


下 面 按 照 以 上 设计 实现 一 个 http 过 小 模 块 ， 以 此 作为 例子 说 明 slab 
共享 内 存 池 的 用 法 。 


16.2.1 共享 内 存 中 的 数据 结构 


对 于 每 一 条 访问 记录 ， 需 要 包含 3 条 数据 : IP+URL 的 变 长 字符 串 
(URL 长 度 变 化 范围 很 大 ， 不 能 按照 最 大 长 度 分 配 等 长 的 内 存 存放 ， 
这 样 太 浪费 ) 、 描 述 红 黑 树 结 点 的 结构 体 、 最 近 访 问 时 间 。 如 果 为 每 
条 记录 分 配 3 块 内 存 各 自 独 立 存放 ， 似 乎 是 很 自然 的 、 符 合 软件 工程 的 
行为 。 然 而 ， 应 当 考 虑 到 Slab 内 存 管理 机 制 因为 强调 速度 而 采用 了 best- 
fit 思 想 ， 这 么 做 会 产生 最 大 1 倍 内 存 的 浪费 ， 所 以 ， 在 设计 数据 存储 时 
应 当 尽量 把 1 条 记 杂 的 3 条 数据 放 在 1 块 连续 内 存 上 。 如 何 实现 呢 ? 


先 回 顾 下 7.5.3 廊 中 给 出 的 ngx_rbtree_node _t 的 定义 : 


typedef struct ngx_rbtree node s ngx_rbtree node t; 
struct ngx_rbtree node sf{ 
// 每 个 结 点 的 


hash 值 


ngx_rbtree_key_t key; 
A/ 在 手 结 点 ， 


Nginx 红 黑 树 自动 维护 


ngx_rbtree_node _t *]eft; 
// 厂子 结 点 ， 


Nginx 红 黑 树 自动 维护 


ngx_rbtree_node t *right; 
// 父 节点 ， 


Nginx 红 黑 树 自动 维护 


ngx_rbtree_node_t *parent; 
// 红色 、 黑 色 


Nginx 红 黑 树 自动 维护 


u_char color; 
XX 再 

u_char data; 
}; 


红 黑 树 中 的 每 个 结 点 都 对 应 着 一 个 ngx_rbtree_node_t 结 构 体 ， 它 的 
key 成 员 必 须要 设置 ， 因 为 比较 哈 希 过 的 整 型 要 比 挨 个 比较 字符 串 中 的 
字符 快 得 多 ! 它 的 data 成 员 目 前 是 无 用 的 ， 其 他 成 员 由 ngx_rbtree 目 行 
处 理 。 


接着 ngx_rbtree_node_t 的 color 成 员 之 后 〈 轿 盖 data 成 员 ) ， 开 始 定 
义 我 们 的 结构 体 ngx_http_testslab_node_t， 如 下 所 示 : 


typedef struct { 
// 对 应 于 


ngx_rbtree_node tt 最 后 一 个 


data 成 员 


u_char rbtree_node_data; 
// 按 先后 顺序 把 所 有 访问 结 点 串 起 ， 方 便 淘汰 过 期 结 点 


ngx_queue_t queue; 
// 上 一 次 成 功 访问 该 


URL 的 时 间 ， 精 确 到 毫秒 


ngx_msec_t last; 
// 窗户 端 

IP 地 址 与 

URL 组 合 而 成 的 字符 串 长 度 
u_short len; 


// 以 字符 串 保 存 客户 端 


IP 地 址 与 


URL 
u_char data[1]; 
} ngx_http_testslab node t; 


ngx_http_testslab_node_t 上 接 ngx_rbtree_node_t、 下 接 变 长 字符 串 ， 
一 条 访问 记录 就 是 这 样 存放 在 一 块 连续 内 存 上 的 ， 如 图 16-1 所 示 。 


ngx_rbtree_node_t 的 data 成 员 地 址 可 ngx_http_testslab_node_1 
直接 转换 为 ngx_http_testslab_node_1 的 data 成 员 地 址 可 直接 转换 为 ipturl 


结构 体 的 字符 串 


em i == 


ngx_rhtree_n 


ode_1 ngx_http_test 


slab_node_1 


图 16-1 用 一 段 连续 内 存 存放 红 黑 树 键 、 值 的 内 存 布局 


由 于 多 个 进程 都 要 操作 红 黑 树 ， 描 述 红 黑 树 的 ngx_rbtree_t 和 哨兵 
结 点 ngx_rbtree_node_t 都 必须 存放 在 共享 内 存 中 ， 同 理 ， 淘 汰 链表 的 表 
头 也 需要 存放 在 共享 内 存 中 ， 因 此 下 面 来 定义 结构 体 
ngx_http_testslab_shm_t， 它 会 存放 在 自 进程 启动 起 从 slab 共 享 内 存 里 分 
配 的 第 1 块 内 存 中 : 


// ngx_http_testslab_shm_t 保 存在 共享 内 存 中 


Wh struct 
// 红 黑 树 用 于 快 ; 


ngx_rbtree_t rbtree; 
// 使 


中 
和信 


Nginx 红 黑 树 必须 定义 的 哨兵 结 点 


ngx_rbtree_node sentinel; 


7 史 天 下 操 佣 让 时 交友 的 淘汰 通才 


ngx_queue_t queue; 
} ngx_http_testslab_shm _t; 


我 们 在 哪里 存放 来 自 共 享 内 存 的 ngx_http_testslab_shm t 结 构 体 的 
目 针 昵 ? 在 这 个 例子 中 ， 由 于 仅 有 一 个 http{f} 块 下 的 main 级 别 配置 项 ， 
这 意味 着 对 这 个 模块 而 言 每 个 worker 进 程 仅 含 一 个 main 配 置 结构 体 ， 因 
此 ， 可 以 把 ngx_http_testslab_shm t 的 指针 放 在 这 个 结构 体 里 。 


此 外 ， 描 述 slab 共 享 内 存 的 ngx_slab_pool t 结 构 体 指针 也 可 以 这 样 
放置 。 所 以 ， 我 们 定义 的 配置 结构 体 ngx_http_testslab_conf t 束 是 这 样 


的 : 


// 注意 : 


ngx_http_testslab_conf_t 不 是 放 在 共享 内 存 中 的 


typedef struct { 
// 共享 内 存 大 小 


ssize_t shmsize; 
// 两 次 成 功 访问 所 必须 间隔 的 时 间 


ngx_int_t interval; 
// 操作 共享 内 存 一 定 需要 


ngx_slab_pool_t 结 构 体 


// 这 个 结构 体 也 在 共享 内 存 中 


ngx_slab_pool_t *shpool; 
// 指向 共享 内 存 中 的 


ngx_http_testslab_shm_t 结 构 体 


ngx_http_testslab_shm _t* sh; 
} ngx_http_testslab_conf_t; 


shmsize 和 interval 成 员 仅 为 nginx.conf 里 的 配置 项 ， 其 中 interval 还 用 
于 表示 是 否 通过 配置 项 开局 了 模块 的 功能 。 


16.2.2 ”操作 共 至 内 存 中 的 红 黑 树 与 链表 


中 


企 7.2 下 中 介绍 过 双向 链表 ， 它 的 操作 很 简单 ， 在 这 个 例子 中 当 需 
要 删除 结 点 时 调用 ngx_queue_remove 方 法 ， 淘 汰 结 点 时 则 从 链表 尾部 


开始 遍历 ， 使 用 ngx_queue_last 方 法 可 以 获取 到 尾部 的 结 点 ， 而 插入 新 
结 点 时 用 ngx_queue_insert_head 方 法 插入 链表 首部 即 可 。 


在 7.5 市 中 介绍 过 红 黑 树 ， 删 除 结 点 时 调用 ngx_rbtree_delete 方 法 即 
可 ， 由 于 参数 中 直接 传递 的 是 结 点 指针 ， 因 此 这 里 不 需要 做 任何 处 
理 。 但 是 插入 、 遍 历时 就 稍 复杂 些 ， 因 为 每 个 结 点 的 真实 关键 字 是 一 
个 变 长 字符 串 ，ngx_rbtree_node_t 中 的 key 成 员 放 的 是 字符 串 的 hash 值 ， 
所 以 插入 函数 时 不 能 直接 使 用 预 置 的 ngx_rbtree_insert_value 方 法 。 我 们 
需要 定义 一 个 新 的 insert 方 法 ， 并 在 初始 化 红 黑 树 时 把 该 方法 传递 给 
ngx_rbtree_init 的 第 3 个 参数 。 当 然 ， 定义 一 个 新 的 insert 方 法 没有 想象 
中 那么 难 ， 只 需要 参考 ngx_rbtree_insert_value 方 法 的 实现 即 可 ， 该 方法 
认为 ngx_rbtree_node_t 中 的 key 成 员 就 是 关键 字 ， 而 我 们 则 认为 字符 串 
才 是 真正 的 关键 字 ，key 仅 用 于 加 速 操 作 红 黑 树 ， 所 以 稍微 改 改 就 可 以 
用 了 。 


读者 朋友 在 继续 阅读 前 可 以 先 浏览 下 src/core/mgx_rbtree.c 中 的 
ngx_rbtree_insert_value 方 法 源码 ， 这 里 不 再 列 出 。 


void 
ngx_rbtree_insert_value(ngx_rbtree node t *temp, ngx_rbtree node t *node, 
ngx_rbtree_node_t *sentinel) 


毛 春 ， 开 始 实 现 针 对 图 16-1 中 这 种 内 存 布局 记录 的 红 淋 树 搬入 方法 


ngx_http_testslab_rbtree_insert_value: 


static void 
ngx_http_testslab_rbtree_ insert_ value(ngx_rbtree node t *temp, 
ngx_rbtree_ node t *node, ngx_rbtree node t *sentinel) 


{ 
ngx_rbtree_node_t Ws 
ngx_http_testslab_node_t *]lrn, *lrnt; 
for ( ;; ) i 
// ngx_rbtree_node_t 中 的 
key 仅 为 
hash 值 
// 先 比较 整 型 的 
key 可 以 加 快 插入 速度 


if (node->key < temp->key) { 
p = &temp->left; 

} else if (node->key > temp->key) { 
p = &temp->right,; 

} else { /* node->key == temp->key */ 
// 从 


data 成 员 开 始 就 是 


ngx_http_testslab_node_t 结 构 体 


lrn = (ngx_http_testslab node t *) &node->data; 

lrnt = (ngx_http_testslab_node t *) &temp->data,; 

p = (ngx_memn2cmp(l4rn->data, lrnt->data, lrn->len, lrnt->len) < 0) 
&temp->left : &temp->right; 


if (*p == sentinel) { 
break; 
} 


temp = *p; 
} 
*p = node; 
node->parent = temp; 
node->left = sentinel; 
node->right = sentinel; 
ngx_rbt_red(node); 


在 实现 了 插入 方法 后 ， 束 可 以 像 下 面 这 样 初始 化 红 淡 树 了 : 


ngx_http_testslab_conf_t *conf,; 


ngx_rbtree_init(&conf->sh->rbtree, &conf->sh->sentinel, 
ngx_http_testslab_rbtree_insert_value); 


下 面 ， 我 们 开始 实现 含有 业务 逻辑 的 ngx_http_testslab_ lookup 和 
ngx_http_testslab_expire 方 法 ， 前 者 含有 红 黑 树 的 遍历 。 


ngx_http_testslab_lookup 负 责 在 http 请 求 到 来 时 ， 首 先 利用 红 黑 树 
的 快速 检索 特性 ， 看 一 看 共享 内 存 中 是 否 存 在 访问 记录 。 查 找 记录 
上 时， 首先 查找 hash 值 ， 若 相同 再 比较 字符 串 ， 在 该 过 程 中 都 按 左 子 树 小 
于 右 子 树 的 规则 进行 。 如 果 查 找到 访问 记录 ， 则 检查 上 次 访问 的 时 间 
距 当 前 的 上 时间差 是 否 超 过 允许 阀 值 ， 超 过 了 则 更 新 上 次 访问 的 时 间 ， 
并 把 这 条 记录 重新 放 到 双向 链表 的 首部 (因为 眼下 这 条 记录 最 不 容易 
被 淘汰 ) ， 同 时 返回 NGX_DECLINED 表 示人 允许 访问 ， 若 没有 超过 阀 
值 ， 则 返回 NGX_HTTP_FORBIDDEN 表 示 拒 绝 访问 。 如 果 红 黑 树 中 没 
有 查找 到 这 条 记录 ， 则 向 slab 共 享 内 存 中 分 配 一 条 记录 所 需 大 小 的 内 存 
块 ， 并 设置 好 相应 的 值 ， 同 时 返回 NGX_DECLINED 表 示人 允许 访问 。 代 
码 如 下 : 


// rr 是 


http 请 求 ， 因 为 只 有 请 求 执行 时 才 会 调 


ngx_http_testslab_lookup 
// conf 是 全 局 配置 结构 体 


// data 和 


len 参 数 表示 


IP+URL 字 符 串 ， 而 


字符 
hash 则 是 该 字符 串 的 


hash 值 


static ngx_int_t 
ngx_http_testslab_lookup(ngx_http_request _t *r, 


ngx_http_testslab_conf_t *conf, 
ngx_uint_t hash, 

u_char* data, 

size_t len) 


{ 
size_t size; 
ngx_int_t re; 
ngx_time_t *tp; 
ngx_msec_t now; 
ngx_msec_int_t ms ， 
ngx_rbtree_node_t *node, *sentinel; 
ngx_http_testslab node t *1r; 
// 取 到 当前 时 间 
tp = ngx_timeofday(); 
now = (ngx_msec_t) (tp->sec * 1000 + tp->msec); 
node = conf->sh->rbtree.root,; 
sentinel = conf->sh->rbtree.sentinel,; 
while (node != sentinel) { 
// 先 由 
hash 值 快速 查找 请 求 
If (hash < node->key) { 
node = node->left,; 
continue; 
} 
if (hash > node->key) { 
node = node->right; 
continue; 
} 
/* hash == node->key */ 
lr = (ngx_http_testslab node t *) &node->data; 
// 精确 比较 
IP+URL 字 符 串 


rc = ngx_memn2cmp(data, lr->data, len, (size _t) lr->len); 
if (rc == 


) { 
// 找到 后 先 取 得 当前 时 间 与 上 次 访问 时 间 之 差 


ms = (ngx_msec_int_t) (now - lr->last); 
// 判断 是 否 超 过 阀 值 


if (ms > conf->interval) { 
// 允许 访问 ， 则 更 新 这 个 结 点 的 上 次 访问 时 间 


lr->last = now; 
// 不 需要 修改 该 结 点 在 红 黑 树 中 的 结构 


// 但 需要 将 这 个 结 点 移动 到 链表 首部 


ngx_queue_remove(&lr->queue); 
ngx_queue_insert_head(&conf->sh->queue, &lr->queue); 


NGX_DECLINED 表 示 当 前 


handler 人 允许 访问 ， 继 续 向 下 执行 


10.6.7 节 


参见 


return NGX_DECLINED ; 


} else { 


// 向 客户 端 返回 


403 拒 绝 访 问 ， 


» 


见 


10.6.7 节 


return NGX_HTTP_FORBIDDEN ， 


} 


node = (rc < 0) node->left : 


} 
// 获取 到 连续 内 存 块 的 长 度 


node->right; 


size = offsetof(ngx_rbtree node t, data) 
+ offsetof(ngx_http_testslab_ node _t, data) 


+ len; 
// 首先 尝试 淘汰 过 期 


node， 以 释放 出 更 多 共享 内 存 


ngx_http_testslab_expire(r, conf); 
// 释放 完 过 期 访问 记录 后 就 有 更 大 机 会 分 配 到 共享 内 在 


// 由 于 已 经 加 过 锁 ， 所 以 没有 调 


ngx_slab_alloc 方 法 


node = ngx_slab_ alloc_ locked(conf->shpool, size); 


if (node == NULL) { 


// 共享 内 存 不 足 时 人 简 和 


返 错 ， 


return NGX_ERROR; 


} 
// key 里 存放 


ip+ur1 字 符 串 的 


hash 值 以 加 快 访问 红 黑 树 的 速度 


node->key = hash,; 


这 个 简 六 


的 例子 没有 做 更 多 的 处 到 


lr = (ngx_http_testslab node t *) &node->data; 


// 设置 访问 时 间 


lr->last = now; 
// 将 连续 内 存 块 中 的 字符 串 及 其 长 度 设 好 


lr->len = (u_char) len; 
ngx_memcpy(lr->data, data, len); 
// 插入 红 黑 树 


ngx_rbtree_insert(&conf->sh->rbtree, node); 
// 插入 链表 首部 


ngx_queue_insert_head(&conf->sh->queue, &]lr->queue); 
// 允许 访问 ， 参 见 


10.6.7 节 


return NGX_DECLINED,; 


ngx_http_testslab_expire 方 法 则 负责 从 双 回 链表 的 尾部 开始 检查 访 
问 记 录 ， 如 采 上 次 访问 的 时 间距 当前 已 经 超出 了 允许 阀 值 ， 则 可 以 删 
除 访问 记录 从 而 释放 共享 内 存 。 代 码 如 下 : 


static void 
ngx_http_testslab_expire(ngx_http_request _t *r,ngx_http_testslab_conf_t *conf) 


ngx_time_t *tp; 
ngx_msec_t now; 
ngx_queue_t “0 
ngx_msec_int_t ms ， 
ngx_rbtree_node t *node 


ngx_http_testslab node t *1r; 
// 取出 缓存 的 当前 时 间 


tp = ngx_timeofday() ， 
now = (ngx_msec _t) (tp->sec * 1000 + tp->msec); 
// 循环 的 结束 条 件 为 ， 要 么 链表 空 了 ， 要 么 遇 到 了 一 个 不 需要 淘汰 的 结 点 


while (1) { 
// 要 先 判 断 链 表 是 否 为 空 


If (ngx_queue empty(&conf->sh->queue)) { 
// 链表 为 空 则 结束 循环 


return; 


// 从 链表 尾部 开始 淘汰 


A 


// 因为 最 新 访问 的 记录 会 更 新 到 链表 首部 ， 所 以 尾部 是 最 老 的 记录 


dq = ngx_queue_ last(&conf->sh->queue); 
// ngx_queue_data 可 以 取出 


ngx_queue_t 成 员 所 在 结构 体 的 首 地 址 


lr = ngx_queue data(q, ngx_http_testslab node t, queue); 
// 可 以 从 


lr 地 址 向 前 找到 


ngx_rbtree_node t 
node = (ngx_rbtree node t *) 
((u_char *) lr - offsetof(ngx_rbtree node t, data)); 


// 取 当 前 时 间 与 上 次 成 功 访问 的 时 间 之 差 


ms = (ngx_msec_int_t) (now - lr->last); 
if (ms < conf->interval) { 
// 若 当 前 结 点 没有 淘汰 掉 ， 则 后 续 结 点 也 不 需要 淘汰 


return; 


} 
// 将 淘汰 结 点 移出 双向 链表 


ngx_queue_remove(q) 
// 将 淘汰 结 点 移出 红 黑 树 


ngx_rbtree_ delete(&conf->sh->rbtree, node); 
// 此 时 再 释放 这 块 共享 内 丰 


ngx_slab_free locked(conf->shpool, node); 


准备 工作 就 绪 ， 接 下 来 可 以 开始 定义 http 过 滤 模 块 了 。 


16.2.3 ”解析 配置 文件 


首先 定义 ngx_command_t 结 构 体 处 理 nginx.conf 配 置 文件 ， 并 在 其 
后 接 2 个 参数 的 test_slab 配 置 项 ， 它 仅 能 存放 在 http{f} 块 中 ， 代 码 如 下 : 


static ngx_command t ngx_http_testslab commands[] = { 
{ ngx_string("test_slab"), 
// 仅 支 持 在 


http 块 下 配 


test_slab 配 置 项 


// 必须 携带 
2 个 参数 ， 前 者 为 两 次 成 功 访问 同一 


URL 时 的 最 小 间隔 秒 数 


// 后 者 为 共享 内 存 的 大 小 


NGX_HTTP_MAIN_CONF|NGX_CONF_TAKE2， 
ngx_http_testslab_createmem, 

09, 

09, 

NULL }, 

ngx_null_ command 


}; 


下 面 实 现 解析 配置 项 的 方法 ngx_http_testslab_createmem。 只 有 当 
发 现 test_slab 配 置 项 上 是 其 后 跟着 的 参数 都 合法 时 ， 才 会 开启 模块 的 限 速 
功能 。 代 人 码 如 下 : 


static char * 
ngx_http_testslab_createmem(ngx_conf_t *cf, ngx_command_t *cmd, void *conf) 


ngx_str_t *value; 
ngx_shm_zone_t *shm_zone; 
// conf 参 数 为 


ngx_http_testslab_create_main_conf 创 建 的 结构 体 


ngx_http_testslab_ conf_t *mconf = (ngx_http_testslab conf_t *)conf; 
// 这 块 共享 内 存 的 名 字 


ngx_str_t name = ngx_string("test_slab_shm"); 
// 取 到 


test_slab 配 置 项 后 的 参数 数组 


value = cf->args->elts,; 


// 获取 两 次 成 功 访问 的 时 间 间 隔 ， 注 意 时 间 单 位 


mconf->interval = 1000*ngx_atoi(value[1].data, value[1].1en); 
if (mconf->interval == NGX_ERROR || mconf->interval == 0) { 


// 约定 设置 为 
-1 束 关 闭 模 块 的 限 速 功能 


mconf->interval = -1; 
return "invalid value" ， 
} 
// 获取 共享 内 存 大 小 


mconf->shmsize = ngx_parse_size(&value[2]); 
If (mconf->shmsize == (ssize_t) NGX_ERROR || mconf->shmsize == 0) { 
// 关闭 模块 的 限 速 功能 


mconf->interval = -1; 
return "invalid value",; 
} y 
// 要 求 


Nginx 准 备 分 配 共享 内 在 


shm_zone = ngx_shared memory_add(cf, &name, mconf->shmsize, 
&ngx_http_testslab_ module); 


if (shm zone == NULL) { 
// 关闭 模块 的 限 速 功能 


mconf->interval = -1; 
return NGX_CONF_ERROR 
} 
// 设置 共享 内 存 分 配 成 功 后 的 


互 


调 方法 


shm_zone->init = ngx_http_testslab_shm_init,; 
// 设置 


调 时 可 以 


init 


data 中 获取 


ngx_http_testslab_conf_t 配 置 结构 体 


shm_zone->data = mconf， 
return NGX_CONF_OK ， 


全 局 ngx_http_testslab_conf t 配 置 结构 体 的 生成 由 
ngx_http_testslab_create_main_conf 方 法 负责 ， 它 会 设置 到 


ngx_http_module_t 中 。 其 代码 如 下 : 


static void * 
ngx_http_testslab_create main conf(ngx_conf_t *cf) 


ngx_http_testslab_conf_t *conf,; 
// 在 


worker 内 存 中 分 配 配置 结构 体 


conf = ngx_pcalloc(cf->pool, sizeof(ngx_http_testslab_conf_t)); 
If (conf == NULL) { 
return NULL; 


} 
// interval 初 始 化 为 


- 工 ， 同 时 用 于 判断 是 否 未 开局 模块 的 限 速 功能 


conf->interval = -1; 
conf->shmsize = -1; 
return conf,; 


ngx_shared_memory_add 执 行 成 功 后 ，Nginx 将 会 在 所 有 配置 文件 
解析 完毕 后 开始 分 配 共享 内 存 ， 并 在 名 为 test_slab_shm 的 Jslab 共 享 内 存 
初始 化 完毕 后 回调 ngx_http_testslab_shm _init 方 法 ， 该 方法 实现 如 下 : 


static ngx_int_t 
ngx_http_testslab_shm_ init(ngx_shm_zone_t *shm zone, void *data) 


ngx_http_testslab_ conf_t *conf,; 

// data 可 能 为 空 ， 也 可 能 是 上 次 
ngx_http_testslab_shm_init 执 行 完 成 后 的 
shm_zone->data 

ngx_http_testslab_conf_t *oconf = data; 


size_t len; 
// shm_zone->data 和 存放 着 本 次 初始 化 


cycle 时 创建 的 


ngx_http_testslab_conf_t 配 置 结构 体 


conf = (ngx_http_testslab conf_t *)shm zone->data; 
// 判断 是 否 为 


reload 配 置 项 后 导致 的 初始 化 共享 内 丰 


if (oconf) { 
// 本 次 初始 化 的 共享 内 存 不 是 新 创建 的 


// 此 时 ， 


data 成 员 里 就 是 上 次 创建 的 


ngx_http_testslab_conf_t 
// 将 


sh 和 


shpool 指 针 指向 旧 的 共享 内 存 即 可 


conf->sh = oconf->sh,; 
conf->shpool = oconf->shpool; 
return NGX_OK， 


} 
// shm.addr 里 放 着 共享 内 存 首 地 址 


:ngx_slab_pool_t 结 构 体 


conf->shpool = (ngx_slab _ pool t *) shm zone->shm.addr; 


// slab 共 享 内 存 中 每 一 次 分 配 的 内 存 都 用 于 存放 


ngx_http_testslab_shm_t 
conf->sh = ngx_slab_alloc(conf->shpool, sizeof(ngx_http_testslab_shm_t)); 
If (conf->sh == NULL) { 
return NGX_ERROR,; 
} 


conf->shpool->data = conf->sh; 
// 初始 化 红 黑 树 


ngx_rbtree_init(&conf->sh->rbtree, &conf->sh->sentinel, 
ngx_http_testslab_rbtree_insert_value); 


// 初始 化 按 访问 时 间 排 序 的 链 寻 


AI 


ngx_queue_init(&conf->sh->queue); 
// slab 操 作 共 享 内 存 出 现 错误 时 ， 其 


log 输 出 会 将 


1l0g_ctx 字 符 串 作为 后 级 ， 以 方便 识别 


len = sizeof(" in testslab \"\"") + shm zone->shm.name.1len; 
conf->shpool->log ctx = ngx_slab_alloc(conf->shpool, len); 
if (conf->shpool->log ctx == NULL) { 


return NGX_ERROR; 


} 

ngx_sprintf(conf->shpool->log_ ctx, " in testslab \"%V\"%zZ", 
&shm_zone->shm.name); 

return NGX_OK， 


16.2.4 ”定义 模块 


先 定义 http 模 块 的 回调 接口 ngx_http_testslab_module_ctx， 设 置 main 
级 别 配置 结构 体 的 生成 方法 为 ngx_http_testslab_create_main_conf (因为 
是 main 级 别 ， 所 以 不 需要 实现 其 merge 合 并 配置 项 方法 ) ， 再 设置 http 
配置 项 解析 完毕 后 的 回调 方法 ngx_http_testslab_init， 用 于 在 11 个 http 请 
求 处 理 阶段 中 选择 一 个 处 理 请 求 ， 如 下 所 示 : 


static ngx_http_module t ngx_http_testslab module ctx = 


{ 
NULL， /* preconfiguration */ 
ngx_http_testslab_init, /* postconfiguration */ 
ngx_http_testslab_create main conf, /* create main configuration */ 
NULL， /* init main configuration */ 
NULL， /* create Server configuration */ 
NULL， /* merge Server configuration */ 
NULL, /* create location configuration */ 
NULL /* merge location configuration */ 
}; 


ngx_http_testslab_init 方 法 用 于 设置 本 模块 在 
NGX_HTTP PREACCESS PHASE 阶段 生效 ， 代 码 如 下 : 


static ngx_int_t 
ngx_http_testslab_init(ngx_conf_t *cf) 


ngx_http_handler_pt hs 

ngx_http_core main conf_t *cmcf; 

cmcf = ngx_http_conf_get_module main_ conf(cf, ngx_http_core_ module); 
// 设置 模块 在 


NGX_HTTP_PREACCESS_PHASE 阶 段 介 入 请 求 的 处 理 


h = ngx_array_push(&cmcf->phases[NGX_HTTP_PREACCESS_PHASE] .handlers) 
if (h == NULL) { 
return NGX_ERROR 


} 
// 设置 请 求 的 处 理 方法 


*h = ngx_http_testslab_handler; 
return NGX_OK， 


这 里 请 求 的 处 理 方法 被 设置 为 ngx_http_testslab_handler 了 ， 因 为 在 
15.2.2 节 中 已 经 准备 好 了 ngx_http_testslab_lookup 方 法 ， 所 以 它 的 实现 就 
变 得 很 简 单 ， 如 下 所 示 : 


人 


static ngx_int_t 
ngx_http_testslab_handler(ngx_http_request_t *r) 


size_t len; 
Uint32_t hash; 
ngx_int_t re; 


ngx_http_testslab_conf_t *conf; 

conf = ngx_http_get module main conf(r, ngx_http_testslab module); 
rc = NGX_DECLINED,; 

// 如 果 没 有 配 


test_slab， 或 者 


test_slab 参 数 错误 ， 返 回 


NGX_DECLINED 继 续 执 行 下 一 个 


http handler 

if (conf->interval == -1) 
return rc; 

// 以 客户 端 


IP 地 址 ( 


r->connection->addr_text 中 已 经 保存 了 解析 出 的 


IP 字 符 串 ) 


// 和 


ur1 来 识别 同一 请 求 


len = r->connection->addr_text.len + rr->uri.len' 
u_char* data = ngx_palloc(r->pool, len); 


ngx_memcpy(data, r->uri.data, r->uri.1len); 

ngx_memcpy(data+r->uri.len, r->connection->addr_text.data, r->connection- 
>addr_text. len)， 

// 使 


crc32 算 法 将 


// hash 码 作为 红 黑 树 的 关键 字 来 提高 效率 


hash = ngx_crc32_short(data, len); 


// 多 进程 同时 操作 同一 共享 内 存 ， 需 要 加 锁 


ngx_shmtx_lock(&conf->shpool->mutex); 

rc = ngx_http_testslab_ lookup(r, conf, hash, data, len); 
ngx_shmtx_unlock(&conf->shpool->mutex ); 

return rc; 


最 后 ， 定 义 ngx_http_testslab_module 模 块 : 


ngx_module t ngx_http_testslab module = 


{ 
NGX_MODULE_V1, 
&ngx_http_testslab_module_ctx, /* module context */ 
ngx_http_testslab_commands, /* module directives */ 
NGX_HTTP_MODULE， /* module type */ 
NULL, /* init master */ 
NULL, /* init module */ 
NULL, /* init process */ 
NULL, /* init thread */ 
NULL, /* exit thread */ 
NULL, /* exit process */ 
NULL, /* exit master */ 
NGX_MODULE_V1_PADDING 

}; 


这 样 ， 一 个 文 持 多 进程 间 共 享 数据 、 共 同 限制 用 户 请 求 访问 速度 
的 模块 束 完 成 了 。 


16.3 slab 内 存 管 理 的 实现 原理 


怎样 动态 地 管理 内 存 呢 ? 先 看 看 需要 面 对 的 两 个 主要 问题 : 
-在 时 间 上 ， 使 用 者 会 随机 地 申请 分 配 、 释 放 内 存 ; 
-在 空间 上 ， 每 次 申请 分 配 的 内 存 大 小 也 是 随机 的 。 


这 两 个 问题 将 给 内 存 分 配 算法 市 来 很 大 的 挑战 ， 当 多 次 分 配 、 释 
放 不 同 大 小 的 内 存 后 ， 将 不 可 避免 地 造成 内 存 碎片 ， 而 内 存 人 肆 片 会 造 
成 内 存 浪费 、 执 行 速度 变 慢 ! 常见 的 算法 有 2 个 设计 方向 :first-fit 和 
best-fit。 用 最 位 单 的 实现 方式 来 摘 述 这 2 个 算法 就 是 ， 奉 已 使 用 的 内 存 
之 间 有 许多 不 等 长 的 空 内 内 存 ， 那 么 分 配 内 存 时 ，first-fit 将 从 头 裔 历 空 
内 内 存 块 构成 的 链表 ， 当 找到 的 第 1 块 空间 大 于 请 求 size 的 内 存 块 时 ， 
器 把 它 返 回 给 申请 着 ，best-fit 则 不 然 ， 它 也 会 通 历 空 内 链表， 但 如 下 一 
块 空闲 内 存 的 空间 远大 于 请 求 size， 为 了 避免 浪费 ， 它 会 继续 向 后 遍 
历 ， 看 看 有 没有 恰好 适合 申请 大 小 的 空 几 内 存 块 ， 这 个 算法 将 试图 返 
回 最 适合 〈 例 如 内 存 块 大 小 等 于 或 者 略 大 于 申请 size) 的 内 存 块 。 这 
样 ，first-ft 和 best-fit 的 优 殷 仿佛 已 一 目 了 然 : 前 者 分 配 的 速度 更 快 ， 但 
内 存 浪 费 得 多 ， 后 者 的 分 配 速 度 慢 一 些 ， 内 存 利 用 率 上 却 更 划算 。 而 
且 ， 前 着 造成 内 存 碎片 的 几率 似乎 要 大 于 后 着 。 


Nginx 的 slab 内 存 分 配方 式 是 基于 best-fit 思 路 的 ， 即 当 我 们 申请 一 
块 内 存 时 ， 它 只 会 返回 恰好 符合 请 求 大 小 的 内 存 块 。 但 是 ， 坊 样 可 以 
更 快速 地 找到 best-fit 内 存 块 呢 ? Nginx 首 先 有 一 个 假 是 ， 所 有 需要 使 用 
slab 内 存 的 模块 请 求 分 配 的 内 存 都 是 比较 小 的 〈 绝 大 部 分 小 于 4KB) 。 
有 了 这 个 假定 ， 束 有 了 一 种 快速 找到 最 合适 内 存 块 的 方法 ， 主 要 包括 5 
个 所 


1) 把 整 块 内 存 按 4KB 分 为 许多 页 ， 这 样 ， 如 果 每 一 页 只 存放 一 种 
回 定 大 小 的 内 存 块 ， 由 于 一 页 上 能 够 分 配 的 内 存 块 数量 是 很 有 限 的 ， 
所 以 可 以 在 页 首 上 用 bitmap 方 式 ， 按 二 进 制 位 表示 页 上 对 应 位 置 的 内 存 
块 是 否 在 使 用 中 。 只 是 遍历 bitmap 二 进 制 位 去 寻找 页 上 的 空闲 内 存 块 ， 
使 得 消耗 的 时 间 很 有 限 ， 例 如 bitmap 占 用 的 内 存 空 间 小 导致 CPU 缓存 命 
中 率 高 ， 可 以 按 32 或 64 位 这 样 的 总 线 长 度 去 寻找 空 采 位 以 减少 访问 次 


所 有 空闲 页 构成 链表 


ngx_slab_page_t 


ngx_slab_page_t 


ngx_slab_page_t 


ngx_slab_page_t 


于 相应 slot 下 is 


ngx_slab_page_t 


全 满 页 自动 
脱离 半 满 页 
链表 


ngx_slab_page_t+ 


允许 1 个 超大 
块 使 用 1 个 或 
者 多 个 页 面 


ngx_slab_page_t 


ngx_slab_page_t 


图 16-2 _ slab 内存 示意 图 


2) 基于 空间 换 时 间 的 思想 ，slab 内 存 分 配器 会 把 请 求 分 配 的 内 存 
大 小 简化 为 极为 有 限 的 几 种 (简化 的 方法 有 很 多 ， 例 如 可 以 按照 
fibonacci 方 法 进行 ) ， 而 Nginx slab 是 按 2 的 倍数 ， 将 内 存 块 分 为 8、 
16、32、64...…….. 字 节 ， 当 申请 的 字 广 数 大 于 8 小 于 等 于 16 时 ， 束 会 使 用 
16 字 市 的 内 存 块 ， 以 此 类 推 。 所 以 ， 一 种 页 面 若 存放 的 内 存 块 大 小 为 N 
字 节 ， 那 么 ， 使 用 者 申请 的 内 存在 NM2+1 与 N 之 间 时 ， 都 将 使 用 这 种 页 
面 。 这 样 最 多 会 造成 一 倍 内 存 的 浪费 ， 但 使 得 页 种 类 大 大 减少 了 ， 这 
会 降低 雄 片 的 产生 ， 提 高 内 存 的 利用 率 。 


3) 让 有 限 的 几 种 页 面 构成 链表 ， 且 各 链表 按 序 保存 在 数组 中 ， 这 
样 一 来 ， 用 直接 寻 址 法 束 可 以 快速 找到 。 在 Nginx slab 中 ， 用 slots 数 组 
来 存放 链表 首页 。 例 如 ， 如 果 申 请 的 内 存 大 小 为 30 子 方 ， 那 么 根据 最 
小 的 内 存 块 为 8 字 市 ， 可 以 算出 从 小 到 大 第 3 种 内 存 块 存 放 的 内 存 大 小 
为 32 子 三， 符合 要 求 ， 从 slots 数 组 中 取 第 3 个 元 素 则 可 以 寻找 到 32 字 市 
的 页 面 。 


4) 这 些 页 面 中 分 为 空 几 页 、 半 满 页 、 全 满 页 。 为 什么 要 这 么 划分 
呢 ? 因为 上 述 的 同 种 页 面 链表 不 应 当 包 侣 太 多 元 素 ， 否 则 分 配 内 存 时 
允 历 链表 一 样 非常 耗 时 。 所 以 ， 全 满 页 应 当 脱 离 链表 ， 分 配 内 存 时 不 
应 当 再 访问 到 它 。 空 几 页 应 该 是 超然 的 ， 如 来 这 个 页 面 曾经 为 32 字 市 
的 内 存 块 服务 ， 在 它 又 成 为 空 几 页 时 ， 下 次 便 可 以 为 128 字 市 的 内 存 块 


服务 。 因 此 ， 所 有 的 至 朵 页 会 单独 构成 一 个 空间 页 链表 。 这 里 slots 数 组 
采用 散 列 表 的 思想 ， 用 快速 的 直接 寻 址 方式 将 半 满 页 展现 在 使 用 者 面 
前 。 


5) 虽然 大 部 分 情况 下 申请 分 配 的 内 存 块 是 小 于 4KB 的 ， 但 极 个 别 
可 能 会 有 一 些 大 于 4KB 的 内 存 分 配 请 求 ， 拒 绝 它 则 太 粗 暴 了 “。 对 于 
此 ， 可 以 用 遍历 空闲 页 链表 寻找 地 址 连续 的 空闲 页 来 分 配 ， 例 如 需要 
分 配 11KB 的 内 存 时 ， 则 裔 历 到 3 个 地 址 连续 的 空间 页 即 可 。 


以 上 5 点 ， 就 是 Nginx slab 内 存 管理 方法 的 主要 思想 ， 如 图 16-2 所 


图 16-2 中 ， 每 一 页 都 会 有 一 个 ngx_slab_page_t 结 构 体 摘 述 ，object 
是 申请 分 配 到 的 内 存 存 放 的 对 象 ， 阴 影 方块 是 已 经 分 配 出 的 内 存 块 ， 
空 日 方块 则 是 未 分 配 的 内 存 块 。 下 面 开始 详细 摘 述 slab 算 法 。 


16.3.1 内 存 结构 布局 


每 一 个 slab 内 存 池 对 应 着 一 块 共享 内 存 ， 这 是 一 段 线性 的 连续 的 地 
址 空间 ， 这 里 不 只 是 有 将 要 分 配给 使 用 着 的 应 用 内 存 ， 还 包括 slab 管 理 
结构 ， 事 实 上 从 这 块 内 存 的 肯 地 址 开始 就 古 管 理 结构 体 
ngx_slab_pool_t， 我 们 看 看 它 的 定义 : 


typedef struct { 
// 为 下 面 的 互 不 锁 成 员 


中 


ngx_shmtx_t mutex 服 务 ， 使 用 信和 号 


ngx_shmtx_sh_t Jock; 
// 设 定 的 最 小 内 存 块 长 度 


size_t 
// min_size 对 应 的 位 偏 


移 ， 


量 作 进 程 同 步 


[ 具 时 


内 


到 它 


min_ size， 


因为 


slab 的 算法 大 量 采用 位 操作 ， 从 下 


人 放 是 


UD 
[| 


有 可 以 看 出 先 计算 


// min_shift 很 有 好 处 


size_t 
// 每 一 页 对 应 一 个 


ngx_slab_page_t 页 


ngx_slab_page_t 存 放 在 连 


// 内 存 


构成 数组 ， 而 


地 址 


pages 就 是 数组 


ngx_slab_page_t *pages 


min_shift; 


述 结构 体 ， 所 有 的 


// 所 有 的 空间 页 组 成 一 个 链表 挂 在 
free 成 员 上 

ngx_slab_page_t free; 

// 所 有 的 实际 页 面 全 部 连续 地 放 在 一 起 ， 第 
1 页 的 首 地 址 就 是 
start 

u_char *start; 

// 指向 这 段 共享 内 存 的 尾部 

u_char *end; 

// 在 
14 .8 节 中 曾 介绍 过 
Nginx 封 装 的 互 斥 锁 ， 这 里 就 是 一 个 应 用 范例 

ngx_shmtx_t mutex; 

// Slab 操作 失败 时 会 记录 日 志 ， 为 区 别 是 哪个 
Slab 共享 内 存 出 错 ， 可 以 在 


slab 中 分 配 一 段 内 存 存 


// 放 描 述 的 字符 串 ， 然 后 再 用 


10g_ctx 指 向 这 个 字符 串 


u_char *]og_ctx; 
// 实际 就 是 


'\9'， 它 为 上 面 的 


lo0g_ctx 服 务 ， 当 


1og_ctx 没 有 赋值 时 ， 将 直接 指向 


Zero, 


// 表示 空 字符 串 防 止 出 错 


u_char zero; 
// 由 各 个 使 


slab 的 模块 自由 使 用 ， 


slab 管 理 内 存 时 不 会 用 到 它 


void *data; 


// 指向 所 属 的 


ngx_shm_zone_t 里 的 
ngx_shm_t 成 员 的 


addr 成 员 ， 在 


16 .3.3 节 再 详 述 


void *addr; 
} ngx_slab_pool t; 


从 图 16-3 中 可 以 看 到 ， 这 段 共享 内 存 由 前 至 后 分 为 6 个 部 分 : 
-ngx_slab_pool_t 结 构 体 。 


:不 同 种 类 页 面 的 半 满 页 链表 构成 的 数组 ， 下 文 称 为 slots 数 组 ， 便 
于 大 家 对 照 Nginx 源 码 。 将 共享 内 存 首 地 址 加 上 sizeof(ngx_slab_pool_1) 
即 可 得 到 slots 数 组 。 


.所 有 页 描述 ngx_slab_page_t 构 成 的 数组 ，ngx_slab_pool_t 中 的 
pages 成 员 指 回 这 个 数组 ， 下 文人 策 称 为 pages 数 组 。 


.为 了 让 地 址 对 齐 、 方 便 对 地 址 进行 位 操作 而 “牺牲 的 "不 予 使 用 的 
内 存 。 


真实 的 页 ， 页 中 的 地 址 需要 对 齐 以 便 进 行 位 操作 ， 因 此 其 前 后 会 
有 内 存 浪 费 。ngx_slab_pool_t 中 的 start 成 员 指 向 它 。 


为 了 地 址 对 齐 辆 牲 的 内 存 。 


图 16-3 中 一 个 slab 共 享 内 存 与 ngx_shm_zone_t 和 ngx_cycle_t 的 关系 
将 在 16.3.5 和 中 详 述 。 下 面 来 看 看 slots 数 组 与 pages 数 组 是 如 何 工 作 的 。 
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图 16-3 一 个 slab 共 享 内 存 池 中 的 内 存 布局 


无 论 是 slots 数 组 还 是 pages 数 组 ， 都 是 以 页 为 单位 进行 的 ， 页 在 slab 
管理 设计 中 是 很 核心 的 概念 。 每 一 页 都 有 一 个 描述 结构 ngx_slab_page { 
对 应 ， 下 面 来 看 看 ngx_slab_page_t 的 定义 是 怎样 的 。 


typedef struct ngx_Sslab_page_Ss ngx_slab_page_t; 
struct ngx_Sslab_page_s { 
// 多 用 途 


uintptr_t slab; 
// 指向 双向 链表 中 的 下 一 页 


pp slab_page t *next; 


多 用 途 ， 同 时 用 于 指向 双向 链表 中 的 上 一 页 


uintptr_t prev; 


}; 


从 图 16-2 中 可 以 看 到 ， 页 分 为 空 页 和 已 使 用 页 ， 而 已 使 用 页 中 叉 
分 为 还 有 空 内 空间 可 供 分 配 的 半 满 页 和 完全 分 配 完毕 的 全 满 页 。 每 一 
页 的 大 小 由 ngx_pagesize 变 量 指定 ， 同 时 为 方便 大 量 的 位 操作 ， 还 定义 


~ 


了 页 大 小 对 应 的 位 移 变 量 ngx_pagesize_shift， 如 下 : 


ngx_uint_t ngx_pagesize,; 
ngx_uint_t ngx_pagesize_shift; 


这 两 个 变量 可 在 ngx_os_init 方 法 中 初始 化 ， 如 下 : 


ngx_int_t ngx_os_init(ngx_log t *10g) 


ngx_pagesize = getpagesize(); 
for (n = ngx_pagesize; n >>= 1; ngx_pagesize shift++) { /* void */ } 


全 满 页 和 至 朵 页 较为 答 单 。 全 满 页 不 在 任何 链表 中 ， 它 对 应 的 
ngx_slab_page_t 中 的 next 和 prev 成 员 没 有 任何 链表 功能 。 


所 有 的 空闲 页 构成 1 个 双向 链表 ，ngx_slab_pool t 中 的 free 指 向 这 个 
链表 。 然 而 需要 注意 的 是 ， 并 不 是 每 一 个 空间 页 都 是 该 双向 链表 中 的 
元 素 ， 可 能 存在 多 个 相 邻 的 页 面 中 ， 仅 首页 面 在 链表 中 的 情况 ， 故 而 
目 页 面 的 slab 成 员 大 于 1 时 则 表示 其 后 有 相 邻 的 页 面 ， 这 些 相 邻 的 多 个 
页 面 作为 一 个 链表 元 素 存 在 。 但 是 ， 也 并 不 是 相 邻 的 页 面 一 定 作为 一 
个 链表 元 素 存 在 ， 如 图 16-4 所 示 。 


在 图 16-4 中 ， 有 5 个 连续 的 页 面 ， 左 边 是 接 述 页 面 的 
ngx_slab_page_t 结 构 体 ， 厂 边 则 是 真正 的 页 面 ， 它 们 是 一 一 对 应 的 。 其 
中 ， 第 1、2、4、5 页 面 都 是 至 条 页 ， 第 3 页 则 是 全 满 页 。 而 free 链 表 的 
第 1 个 元 聚 是 第 5 页 ， 第 2 个 元 素 是 第 4 页 ， 可 见 ， 虽 然 第 4、5 页 是 连续 
的 ， 但 是 ， 由 于 分 配 页 面 与 回收 页 面 时 的 时 序 不 同 ， 导 致 这 第 4、5 个 
页 面 间 出 现 了 相 见 不 相识 的 现象 ， 只 能 作为 2 个 链表 元 素 存在 ， 这 将 会 
造成 未 来 分 配 不 出 占用 2 个 页 面 的 大 块 内 存 ， 虽 然 原 本 是 可 以 分 配 出 
的 。 第 3 个 元 陛 是 第 1 页 。 第 2 页 附 在 第 1 页 上 ， 这 还 是 与 分 配 、 回 收 页 
面 的 时 机 有 关 ， 事 实 上 ， 当 slab 内 存 池 刚刚 初始 化 完毕 时 ，free 链 表 中 
只 有 1 个 元 系 ， 吏 是 第 1 个 页 面 ， 该 页 面 的 slab 成 员 值 为 总 页 数 。 第 3 页 
是 全 满 页 ， 其 next 指 针 是 为 NULL， 而 prev 也 没有 指针 的 含义 。 


ngx_slab_pool_t 


的 free 成 员 


该 页 面 是 相 邻 
页 ， 它 的 成 员 
没有 意义 ， 由 
前 面 页 面 的 slab 
表明 其 意义 


全 满 页 脱离 于 
任何 链表 ， 其 
Dext 和 prev 成 
员 没 有 链接 的 
功能 


这 两 个 页 面 虽 
然 相 邻 ， 但 它 
们 之 间 并 不 知 
道 ， 所 以 ,各 
自 独立 的 存在 
于 链表 中 


图 16-4 空闲 页 与 全 满 页 的 ngx_slab_page_t 成 员 意 》 


对 于 半 满 页 ， 存 放 相 同 大 小 内 存 块 的 页 面 会 构成 双 辣 链表 ， 挂 在 
slots 数 组 的 相应 位 置 上 ， 图 16-2 中 已 经 可 以 看 到 。 那 么 ， 页 面 上 完 葛 会 
分 出 多 少 种 不 同 大 小 的 内 存 块 呢 ? 


ngx_slab_pool_t 中 的 min_size 成 员 已 经 指定 了 最 小 内 存 块 的 大 小 ， 
它 在 初始 化 slab 的 方法 ngx_slab_init 中 赋值 : 


void ngx_slab_init(ngx_slab_pool t *pool) 


pool->min_size = 1 << pool->min_shift,; 


而 min_shift 同 样 是 为 了 位 操作 而 设 的 ， 它 的 初始 化 则 是 将 在 16.3.3 
节 介绍 的 ngx_init_zone_pool 方 法 里 赋值 的 : 


static ngx_int_t 
ngx_init_zone_pool(ngx_cycle t *cycle, ngx_shm zone_t *zn) 


ngx_slab pool t *sp; 


sp->min_shift = 3， 


页 面 能 够 存放 的 最 大 内 存 块 大 小 则 由 变量 ngx_slab_max_size 指 


定 : 


// 存放 多 个 内 存 块 的 页 面 中 ， 人 允许 的 最 大 内 存 块 大 小 为 


ngx_slab_max_size 
static ngx_uint_t ngx_slab_max_size; 


它 的 大 小 实际 是 页 面 大 小 的 一 半 (在 ngx_slab_init 方 法 中 设置 ) : 


If (ngx_slab_max_size == 0) { 
ngx_slab_max_size = ngx_pagesize / 2; 
3 


为 什么 是 ngx_pagesize/2 而 个 干脆 就 是 ngx_pagesize 呢 ? 反正 一 个 页 
面 只 存放 一 个 内 存 块 也 可 以 啊 ! 这 是 因为 slab 中 把 不 等 长 的 内 存 大 小 分 
为 了 4 个 大 类 ， 这 样 分 类 后 ， 可 以 使 得 ngx_slab_page_t 的 3 个 成 员 与 实际 
页 面 的 内 存 管 理 在 时 间 和 空间 上 更 有 效率 。 这 4 大 类 的 定义 还 需要 1 个 


变量 ngx_slab_exact_size 的 参与 ， 如 下 : 


static ngx_uint_t ngx_slab_exact_size,; 
static ngx_uint_t ngx_slab_exact_shift,; 


它 的 赋值 也 在 ngx_slab_init 方 法 中 进行 ; 


ngx_slab_exact_size = ngx_pagesize / (8 * sizeof(uintptr_t)); 

for (n = ngx_slab_ exact_ size; n >>= 1; ngx_slab_ exact shift++) { 
/* void */ 

} 


ngx_slab_exact_size 到 底 想 表达 什么 意思 呢 ? 


其 实 就 是 ，ngx_slab_page_t 的 slab 中 是 否 可 以 恰好 以 bitmap 的 方式 
旧 明 页面 中 所 有 内 存 块 的 使 用 状态 。 例 如 ，1 个 二 进 制 位 瓯 可 以 用 0 和 1 
表示 内 存 块 是 否 被 使 用 ，slab 成 员 的 类 型 是 uintptr t， 它 有 


sizeof(uintptr_bD 个 字 节 ， 每 个 字 节 有 8 位 ， 这 样 按 顺 序 slab 就 可 以 表示 


8*sizeof(uintptr_t) 个 内 存 块 。 如 果 1 个 页 面 中 正好 可 以 存放 这 么 多 内 存 
块 ， 那 么 slab 就 可 以 只 当做 bitmap 使 用 ， 此 时 ， 该 页 面 存 放 的 内 存 块 大 
小 就 是 ngx_pagesize/(8*sizeof(uintptr_t))。 以 此 作为 标准 划分 ， 就 可 以 更 
精确 地 使 用 slab 成 员 了 。 表 16-1 就 展示 了 4 类 内 存 是 怎样 划分 的 ， 以 及 
ngx_slab_page_t 各 成 员 的 意义 。 


表 16-1 4 类 内 存 中 页 面 描述 ngx_slab_page_t 的 各 成 员 意 义 


ngx_slab_page ft 


表示 该 页 面 上 存放 的 等 长 内 存 块 | 指向 双向 链表 的 下 | 低 2 位 为 11， 以 NGX 
大 小 ， 当 然 是 用 位 偏 移 的 方式 存放 | 一 个 元 素 ， 如 果 不 在 |SLAB_ SMALL 表示 当前 页 
的 双向 链表 中 ， 则 为 0 | 面 存放 的 是 小 块 内 存 


i , Eee 低 2 位 为 10， 以 NGX 
中 等 内 存 ， 等 于 ngx_ | 作为 bitmap 表示 页 上 的 内 存 块 是 _ i 
a wk 下 已 被 使 用 同上 SLAB EXACT 表示 当前 页 
slab exact size 人 勾 人 中 ee A 2 
= 一 面 存放 的 是 中 等 大 小 的 内 存 


高 TDC STORAGE MAP 
大 块 内 存 ， 大 于 ngx_ Wr = ke 
. . MASK 位 表示 bitmnap， 而 低 TIDC 
slab exact size 而 小 于 和 
二 STORAGE SHIFT MASK 位 表示 存 
放 的 内 存 块 大 小 
超大 内 存 会 使 用 1 页 或 者 多 页 ， 


小 块 内 存 ， 小 于 ngx_ 
Slab _exact size 


低 2 位 为 01， 以 NGX _ 
SLAB BIG 表示 当前 页 面 存 


ngx slab_ max size 放 的 是 大 块 内 存 


这 些 页 都 在 一 起 使 用 。 对 于 这 批 页 

而 中 的 第 1 页 ，slab 的 前 3 位 会 被 低 2 位 为 00， 以 NGX 
设 为 NGX SLAB PAGE START， SLAB_PAGE 表示 当前 页 而 
其 余 位 表示 紧 随 其 后 相 邻 的 同 批 页 是 以 整 页 来 使 用 

面 数 ; 反之 ，slab 会 被 设 为 NGX_ 

SLAB PAGE BUSY 


超大 内 存 ， 大 于 等 于 


ngx slab max size 


16.3.2 ”分配 内 存 流程 


分 配 内 存 时 ， 主 要 涉及 在 半 满 面 上 分 配 和 从 空间 页 上 分 配 新 页 ， 
并 初始 化 这 2 个 流程 ， 而 半 满 页 分 配 义 涉及 在 bitmap 上 查找 空 几 块 ， 对 


于 小 块 、 中 等 、 大 块 内 存 这 三 种 页 面 而 言 ， 其 bitmap 放 置 的 位 置 并 不 相 
同 ， 独 16-5 主 要 说 明了 以 上 和 内容， 下 面 详细 解释 多 中 的 15 个 步 又 。 


1) 如 果 用 户 申请 的 内 存 size 大 于 前 文 介绍 过 的 ngx_slab_max_size 
变量 ， 则 认为 需要 按 页 面 来 分 配 内 存 ， 此 时 跳 转 到 步骤 2;， 人 否则， 由 于 
一 个 页 面 可 以 存放 多 个 内 存 块 ， 因 此 需要 考虑 bitmap ， 此 时 跳 转 到 步 又 
6 继续 执行 。 


2) 判断 需要 分 配 多 少 个 页 面 才能 存放 size 字 节 ， 不 足 1 页 时 按 1 页 
算 ° 如 下 : 


ngx_uint_t pages = (size >> ngx_pagesize shift) + ((size % ngx_pagesize) ?1 : 0) 


1 ) 判断 需要 分 配 的 内 存 大 小 


[ 若 size 小 于 ngx_slab_max_size] aa 于 等 于 ngx_slab_max_size] 


6 ) 算出 恰好 可 放置 size 的 内 存 块 大 小 


2) 根据 请 求 大 小 计算 出 需要 多 少 个 连续 页 面 


7 ) 取得 内 存 块 所 属 半 满 页 链表 slots 


3 ) 从 free 池 中 寻找 连续 的 N 个 页 面 


8 ) 遍历 半 满 页 链表 [判断 是 否 找到 ] 


[没有 半 满 页 ] 


< 


[找到 一 个 半 满 页 ] 


12 ) 从 free 池 中 分 配 1 个 页 面 ) ”[ 演 有 足够 的 空闲 页 ] 


SS 


[分 配 到 1 个 空闲 页 ] 


[当前 页 面 是 全 满 页 ， 脱 离 链 表 ] 


[没有 空闲 页 ] 


GD 这 回 NULL 表 示 失 败 


3 ) 设置 页 面 为 存储 某 长 度 的 页 面 


(根据 himap 判 断 当 前 页 是 否 有 空闲 块 


[找到 空闲 chunk] 


10 ) 置 空闲 内 存 块 对 应 bitmap 位 为 1 
4 ) 设置 hitmap 第 1 位 或 者 前 n 位 为 已 使 用 
[根据 bitmap 判 册页 面 是 否 已 满 ] [找到 空闲 页 


5 ) ] 将 该 页 面 插入 半 满 页 链表 的 首部 
[页 面 还 有 空闲 内 施 块 ] 


<> 


[没有 空闲 内 存 块 ] 


11 ) 将 该 页 面 分 离 出 半 满 链表 


5 ) 返回 内 存 块 首 地 址 


图 16-5 “分 配 slab 内 存 的 流程 


3) 表 历 free 空 有 页 链表 ， 找 到 能 够 容纳 下 size 的 连续 页 面 。 如 果 只 
需要 分 配 1 页 ， 那 么 很 简单 ， 只 要 遍历 到 空闲 页 就 可 以 结束 ， 但 如 果 要 
分 配 多 页 ，free 链 表 中 的 每 个 页 描述 ngx_slab_page_t 中 的 Slab 指明 了 其 
后 连续 的 空闲 页 数 ， 所 以 获取 多 个 连续 页 面 时 ， 只 要 查找 free 链 表 中 每 
个 元 素 的 slab 是 否 大 于 等 于 pages 页 面 数 即 可 。 下 面 针对 分 配 页 面 的 
ngx_slab_alloc_pages 方 法 进行 说 明 : 


static ngx_slab _ page 七 * 
ngx_slab_alloc_pages(ngx_slab_ pool t *pool, ngx_uint_t pages) 


ngx_slab page t *page, *p; 
// 遍历 


free 空 间 页 链表 ， 参 见 图 


16-4 
for (page = pool->free.next; page != &pool->free; page = page->next) { 


/ 表明 连续 页 面 数 足以 容纳 


size 字 节 


if (page->slab >= pages) { 
// 如 果 链 表 中 的 这 个 页 描述 指明 的 连续 页 面 数 大 于 要 求 的 


pages， 只 取 所 需 即 可 ， 


// 将 剩余 的 连续 页 面 数 仍然 作为 一 个 链表 元 素 放 在 


free 池 中 


If (page->slab > pages) { 
// page[pages] 是 这 组 连续 页 面 中 ， 第 


1 个 不 被 使 用 到 的 页 ， 所 以 ， 


// 将 由 它 的 页 描述 


ngx_slab_page_t 中 的 


slab 来 表明 后 续 的 连续 页 数 


page[pages].slab = page->slab - pages; 
// 接 下 来 将 剩余 的 连续 空闲 页 的 第 


1 个 页 描述 


page[pages] 作 为 


// 链表 元 素 插 入 到 


中 ， 取 代 原 先 所 属 的 


free 链 


page 页 描述 


当前 链表 元 素 的 前 后 元 素 


page[pages] 的 链表 指向 


page[pages].next = page->next; 
page[pages].prev = page->prev; 
// 将 链表 的 上 一 个 元 素 指向 


page[pages] 
p = (ngx_slab_page _t *) page->prev; 


p->next = &page[pages]; 
// 将 链表 的 下 一 个 元 素 指向 


page[pages] 
= (uintptr_t) &page[pages]; 


page->next->prev = 
} else { 
// slab 等 于 


pages 时 ， 直 接 将 


page 页 描述 移出 


free 链 表 即 可 


p = (ngx_slab_page _t *) page->prev; 


p->next = page->next,; 
page->next->prev = page->prev; 


} 
// 这 段 连 续 页 面 的 首页 描述 的 


slab 里 ， 高 
3 位 设 
NGX_SLAB_PAGE_START 
page->slab = pages | NGX_SLAB_PAGE_START ， 
// 不 在 链表 中 


page->next = NULL; 
// prev 定 义 页 类 型 : 存放 


size>=ngx_slab_max_size 的 页 级 别 内 存 块 


page->prev = NGX_SLAB_PAGE; 


if (--pages == 0) { 
// 如 果 只 分 配 了 


1 页 ， 此 时 就 可 以 返回 


page 了 
return page; 
} 
// 如 果 分 配 了 连续 多 个 页 面 ， 后 续 的 页 描述 也 需要 初始 化 
for (p = page + 1; pages; pages--) { 
// 连续 页 作为 一 个 内 在 块 一 起 分 配 出 时 ， 非 第 
1 页 的 
slab 都 置 为 


NGX_SLAB_PAGE_BUSY 


p->slab = NGX_SLAB_PAGE_BUSY; 
p->next = NULL; 

p->prev = NGX_SLAB_PAGE; 

p++; 


} 
// 连续 的 各 个 页 描述 都 初始 化 完成 后 ， 返 回 页 


page 

} 

} yy Ey 

// 没有 找到 符合 要 求 的 页 面 ， 返 回 


return page; 


NULL 
return NULL; 


介绍 完 ngx_slab_alloc_pages 方 法 可 知 ， 如 果 找 到 符合 要 求 的 页 面 ， 
那么 跳 到 第 5 步 ， 返 回 页 面 的 首 地 址 即 可 ; 没有 找到 这 样 的 页 面 ， 跳 到 
第 4 步 返 回 NULL 。 


4) 返回 NULL， 表 明 分 配 不 出 新 内 存 ，OutOfMemory 。 
5) 返回 可 以 使 用 的 内 存 块 首 地 址 。 


6) slab 页 面 上 允许 存放 的 内 存 块 以 8 字 节 起 步 ， 若 字 数 在 
ngx_slab_max_size 以 内 时 是 按 2 的 倍数 递增 的 ， 那 么 这 与 第 2 步 按 页 分 


配 时 是 不 同 的 ， 按 页 分 配 时 最 多 浪费 ngx_pagesize-1 字 节 的 内 存 ， 例 如 
分 配 4097 子 让 时 必须 返回 2 个 连续 页 ， 而 按 2 的 倍数 分 配 时 ， 则 最 多 会 
浪费 size-2 字 市 内 存 ， 例 如 分 配 9 字 节 时 应 返回 16 字 市 的 内 存 块 ， 浪 费 


了 7 个 字 有 了 。 


此 时 size 小 于 ngx_slab_max_size， 因 此 要 依据 best-fit 原 则 找 一 个 恰 
好 能 放下 size 的 内 存 块 大 小 。 


7) 取出 所 有 半 满 页 链表 构成 的 slots 数 组 ， 由 于 链表 是 以 内 存 块 从 
小 到 大 以 2 的 整数 倍 按 序 放 在 数组 中 的 ， 所 以 使 用 直接 寻 址 的 方式 找到 
第 6 步 指 示 的 内 存 块 所 属 半 满 页 链表 。 


8) 裔 历 半 满 页 链表 。 如 果 没 有 找到 半 满 页 ， 则 跳 到 第 12 步 去 分 配 
新 页 存放 该 内 存 块 ， 找 到 一 个 半 满 页 ， 则 继续 执行 第 9 步 。 


9) 根据 表 16-1 可 知 ， 当 内 存 块 小 于 ngx_slab_max_size 时 ， 每 页 都 
必须 使 用 bitmap 来 标识 内 存 块 的 使 用 状况 。 而 依据 bitmap 的 存放 位 置 不 
同 ， 又 分 为 小 块 、 中 等 、 大 块 内 存 。 此 时 ， 需 要 根据 第 6 步 算出 的 内 存 
块 大 小 ， 移 找到 pitmap 的 位 置 ， 再 遍历 它 找到 第 1 个 空 亲 的 内 存 块 。 如 
果 找 到 空 帮 内 存 块 ， 则 继续 执行 第 10 步 ， 否 则 ， 这 个 半 满 面 就 名 不 符 
实 了 ， 它 实际 上 束 古 一 个 全 满 页 ， 所 以 可 以 脱离 半 满 页 链表 了 了， 继续 
第 8 步 授 历 链表 。 


10) 表 先 将 找到 的 空 内 内 存 块 对 应 的 bitmap 位 置 为 1， 以 示 内 存 块 
在 使 用 中 。 接 着 ,检查 这 是 否 为 当前 页 的 最 后 一 个 空 用 内 存 块 ， 如 果 
征 ， 则 半 满 页 变 为 全 满 页 ， 跳 到 第 11 步 执行 ; 否则， 直接 跳 到 第 5 步 ， 
返回 这 个 内 存 块 地 址 。 


11) 将 页 面 分 离 出 半 满 页 链表 ， 再 跳 转 到 第 5 步 。 


12) 未 找到 半 满 页 ， 需 要 从 free 空 是 页 链表 中 申请 出 新 的 一 页 ， 参 


13) 设置 新 页 面 存放 的 内 存 块 长 度 为 第 6 步 指定 的 值 。 同 时 设置 它 
的 页 搞 述 的 prev 成 员 低 位 ， 指 明 息 是 小 块 、 中 等 还 是 大 块 内 存 块 页 面 。 


14) 新 页 面 分 配 出 了 第 1 个 内 存 块 ， 对 于 中 等 、 大 块 内 存 页 来 说 ， 
置 bitmap 第 1 位 为 1 即 可 ， 但 对 于 小 块 内 存 页 ， 由 于 它 的 前 几 个 内 存 块 是 
用 于 bitmap 的 ， 因 此 不 能 再 次 被 使 用 ， 所 以 对 应 的 bit 位 需要 置 为 71， 并 
把 下 一 个 表明 当前 分 配 出 的 内 存 块 的 bit 位 也 置 为 1。 


15) 这 个 新 页 面 由 空闲 页 变 为 半 满 页 ， 因 此 将 页 面 插入 半 满 页 链 
表 的 首部 。 


16.3.3 释放 内 存 流 程 


释放 内 存 时 不 需要 遍历 链表 、bitmap， 所 以 速度 更 快 。 图 16-6 说 明 
了 释放 内 存 的 完整 流程 。 


释放 内 存 的 流程 如 图 16-6 所 示 。 


1) 首先 判断 释放 的 内 存 块 地 址 是 否 合法 ， 依 据 为 是 否 在 
ngx_slab_pool_t 的 start、end 成 员 指示 的 页 面 区 之 间 。 如 采 不 合法 ， 直 接 
结束 释放 流程 ， 例 如 : 


void ngx_slab_free_locked(ngx_slab _ pool t *pool, void *p) 


{ 
If ((u_char *) p < pool->start || (u_char *) p > pool->end) { 
// p 地 址 非法 


2) 从 每 释放 的 内 存 块 地 址 p 可 以 快速 得 到 它 所 属 的 页 描述 结构 
体 ， 如 下 : 


ngx_uint_t n= ((u_char *) p - pool->start) >> ngx_pagesize_ shift,; 
ngx_slab_page_t * page = &pool->pages[n]; 


page 变 量 就 是 页 搬 述 结构 体 ， 在 16.3.4 市 会 详细 介绍 类 似 地 址 位 运 
Es 


3) 根据 页 搬 述 结构 体 的 prev 成 员 ， 得 到 该 页 面 是 用 于 小 块 、 中 
等 、 大 块 的 内 存 ， 或 者 按 页 分 配 的 内 存 。 因 为 存放 小 块 、 中 等 、 大 块 
内 存 的 页 面 含有 bitmap ， 这 样 的 页 面 处 理 时 要 再 次 核实 bitmap 中 p 对 应 


的 bit 位 是 否 为 1， 防 止 重复 释放 ， 此 时 跳 到 第 5 步 执行 ， 如 果 p 当 初 是 按 
页 分 配 的 ， 不 需要 考虑 bitmap ， 释 放 起 来 更 简单 ， 继 续 执 行 第 4 步 。 


4) 由 页 描述 的 slab 成 员 可 以 获得 当前 使 用 的 内 存 究竟 占用 了 多 少 
页 (参考 图 16-5 的 第 3 步 ) ， 如 下 : 


ngx_uint_t pages = Slab & ~NGX_SLAB_PAGE_START 
接着 ， 跳 到 第 11 步 调用 ngx_slab_free_pages 释 放 这 pages 个 页 面 。 


5) 这 个 页 面 存 放 了 多 个 内 存 块 ， 参 考 表 16-1 可 知 ， 从 页 描述 的 
slab 成 员 可 以 获取 这 个 页 面 存放 多 大 的 内 存 块 。 


6) 用 页 大 小 除 以 内 存 块 大 小 ， 可 以 得 到 需要 多 少 个 bit 位 来 存放 
bitmap。 再 根据 地 址 p 与 页 面 首 地 址 的 相对 偏 移 量 ， 计 算出 p 对 应 的 内 存 
块 占 用 了 bitmap 中 的 哪个 bit 位 。 


1 ) 判断 待 释放 的 地 址 是 否 在 共享 内 存 地 址 范围 内 


[ 待 释放 地 址 合法 ] 
2 ) 根据 参数 地 址 与 共享 内 存 起 始 地 址 之 差 ， 获 得 对 应 的 页 描述 


3 ) 由 prev 成 员 的 低 2 位 中 取出 该 页 面 的 类 型 
人 [释放 不 足 半 页 的 大 、 中 、 小 块 内 存 ] 


[释放 跨 1 到 多 页 的 超大 块 内 存 ] 


4 ) 根据 slab 计 算出 待 释 放 的 页 面 数 


[ 待 释放 地 址 不 合法 ] 
5 ) 根据 页 面 类 型 由 slab 取 出 该 页 存储 内 存 块 的 大 小 


6 ) 由 参数 地 址 与 所 在 页 地 址 差 的 偏 移 计算 出 bitmap 位 


7 ) 检查 内 存 块 对 应 bitmap 位 上 是 否 为 已 使 用 


[bitmap 显 示 内 存 块 使 用 中 ， 合 法 ] 
[bitmap 显 示 内 存 块 为 空闲 ， 重 复 释 放 不 处 理 ] 
8 ) 置 该 bitmap 位 为 0， 再 检查 当前 页 是 否 是 全 满 页 


[当前 磺 是 半 满 页 ] 


9 ) 将 当前 页 加 入 半 满 页 链表 的 首位 ， 并 使 slot 指 向 它 


10 ) 检查 当前 页 bitmap 是 否 已 经 没有 已 分 配 chunk 
<> [页 上 还 有 在 使 用 的 chunk] 


[页 上 已 经 没有 任何 chunk] 


11 ) 释放 页 面 到 free 空 闲 页 链表 池 中 SS 


图 16-6 ”释放 slab 内 存 的 流程 


7) 检查 bitmap 中 该 内 存 块 对 应 的 bit 位 是 否 为 1。 如 果 是 1， 那 么 执 
行 第 8 步 继 续 释 放 ; 否则 ， 可 以 认为 当前 是 在 释放 一 个 已 经 被 释放 的 内 
存 ， 结 束 释放 流程 。 


8) 将 这 个 bit 位 由 1 改 为 0， 这 样 如 果 原 先 这 是 一 个 全 满 页 ， 就 会 变 
为 半 满 页， 执行 第 9 步 ， 否 则 ， 直 接 执行 第 10 步 。 


9) 当前 页 面 既 然 由 全 满 页 变 为 半 满 页 ， 束 必须 插入 slots 中 的 半 满 
页 链表 ， 供 下 次 分 配 内 存 时 使 用 。 


10) 检查 bitmap 中 是 否 还 有 值 为 0 的 bit 位 ， 判 断 当 前 页 是 否 变 为 衬 
闲 页 ， 如 有 果 变 成 了 衬 闲 页， 则 执行 第 11 步 将 它 加 入 到 free 链 表 中 。 


11) 回收 页 面 ，ngx_slab_free_pages 方 法 负责 将 这 些 页 面 插入 到 
free 链 表 中 ， 我 们 看 看 它 的 实现 是 怎样 的 : 


static void 
ngx_slab_free_pages(ngx_slab_pool t *pool, ngx_slab_page_t *page, 
ngx_uint_t pages) 


ngx_slab_page_t *prev; 
// page 将 会 加 入 到 


free 链 表 中 ， 连 续 页 面 数 为 


pages， 所 以 把 


slab 置 为 


pages 
page->slab = pages--,; 


// 除了 


page 本 身 ， 检 查 其 后 是 否 还 有 页 面 


if (pages) { 
// 将 紧邻 的 页 画 


描述 结构 体 所 有 成 员 


河 
过 


ngx_memzero(&page[1], pages * sizeof(ngx_slab_page_t)); 


} 
// 将 释放 的 首页 
page 的 页 描述 插入 到 


free 链 表 的 首部 


page->prev = (uintptr_t) &pool->free; 
page->next = pool->free.next; 
page->next->prev = (uintptr_t) page; 
pool->free.next = page; 


} 


16.3.4 如 何 使 用 位 探 作 


本 市 以 较为 复杂 的 小 块 内 存 页 为 例 ， 介 绍 如 何 使 用 位 操作 来 加 速 
分 配 、 释 放 内 存 ， 方 便 读 者 朋友 阅读 星 梁 的 位 操作 部 分 源 代码 。 


除了 NGX_SLAB_PAGE 类 型 的 页 面 ， 每 个 页 面 都 可 以 存放 多 个 内 
存 块 。 这 样 ， 每 个 页 面 都 需要 有 一 个 bitmap 来 表示 每 一 个 内 存 块 究竟 是 
被 使 用 的 还 是 空 几 的 。 然 而 ， 如 果 一 个 页 面 存放 的 内 存 块 大 小 小 于 
ngx_slab_exact_size， 那 么 一 个 uintptr_t 是 存放 不 下 bitmap 的 。 这 时 ,将 
会 使 用 页 面 里 的 前 儿 个 内 存 块 充当 bitmap， 如 图 16-7 所 示 。 


实际 上 图 16-7 接 述 了 一 种 在 小 块 内 存 半 满 页 上 分 配 内 存 的 场景 。 下 
面 简要 地 用 源码 中 用 到 的 各 种 位 操作 来 摘 述 这 一 过 程 。 


ngx_slab_pool t 


slots 数 组 


pages 成 员 


prev 低 2 位 表示 该 
页 存储 小 块 chunk 


start 成 员 

相距 n 个 页 面 
bitmap 中 每 个 二 进 制 位 表示 对 
应 的 内 存 块 是 否 被 使 用 ， 此 时 
从 1100... 置 为 1110... 


所 一 一 一 分 配 到 的 内 存 地 址 


图 16-7 小 块 内 存 页面 的 bitmap 会 直接 占用 页 面 中 的 内 存 


用 户 在 ngx_slab_alloc 方 法 中 申请 size_t size 大 小 的 内 存 ， 而 slab 中 是 
按 2 的 害 来 决定 页 面 能 够 存放 的 内 存 块 大 小 的 。 哪 一 种 大 小 的 内 存 块 恰 


好 能 够 容纳 size 字 下 呢 ? 很 商 单 ， 如 下 所 示 : 


ngx_uint_t shift=1; 
size t s; 
for (s = size - 1; s >>= 1; shift++) { /* void */ } 


这 样 ， 我 们 获得 了 位 操作 必需 的 、 恰 好 容纳 size 字 节 的 内 存 块 的 偏 
移 量 shift。 除 此 以 外 ， 还 需要 拿 到 slots 数 组 ， 这 里 放置 了 半 满 页 构成 的 
链表 ， 从 共享 首 地 址 数 起 ， 加 上 sizeof(ngx_slab_pool_t) 字 节 即 可 拿 到 ， 
如 下 所 示 : 


ngx_slab_pool_t *pool; 


ngx_slab_page_t *slots = (ngx_slab _ page t *) ((u_char *) pool + 
sizeof (ngx_slab_pool_t)); 


slots 数 组 中 按照 内 存 块 大 小 的 顺序 (从 小 到 大 ) ， 依 次 存放 了 各 种 
等 长 块 页 面 构成 的 半 满 页 链表 。 选 用 哪 一 个 slots 数 组 呢 ? 用 shift 偏 移 减 
去 表达 最 小 块 的 min_shift 成 员 即 可 : 


ngx_uint_t Slot = Shift - pool->min_shift; 
ngx_slab_page_t *page = Slots[Slot].next， 


这 样 ，page 就 将 是 一 个 半 满 页 。 如果 slots 中 没有 半 满 页 ， 那 么 page 
是 NULL。 图 16-5 中 描述 的 场景 是 含有 半 满 页 的 ， 所 以 下 面 继 续 基于 这 


个 假定 进行 说 明 。 


接着 ， 我 们 发 现 用 户 和 希望 分 配 的 内 存 块 大 小 是 小 于 
ngX_slab_exact_size 的 ， 此 时 ， 首 移 要 找到 bitmap 的 初始 位 置 ， 准 备 按 
位 来 查找 到 罕 亲 块 。bitmap 其 实 丈 在 页 面 的 首 地 址 上， 怎样 用 位 操作 快 
速 找到 页 面 呢 ? 从 独 16-5 中 可 以 看 到 ngx_slab_pool_t 的 pages 指 针 和 start 
指针 ， 它 们 是 关键 ! 


上 面 找到 的 page 是 半 满 页 的 ngx_slab_page_t 描 述 结构 体 的 首 地 址 ， 
用 它 减 去 pages 就 可 以 得 到 该 页 面 在 整个 lab 中 是 第 N 个 页 面 (这 2 个 相 
减 的 变量 都 是 ngx_slab_page_t* 类 型 ) 。start 是 对 齐 后 slab 第 1 个 页 面 的 
起 始 地 址 ， 所 以 ，start 加 上 N*pagesize 就 可 以 得 到 该 半 满 页 的 实际 页 面 
目地 址 ， 如 下 所 示 : 


uintptr_t p = (page - pool->pages) << ngx_pagesize_ shift; 
uintptr_t* bitmap = (uintptr_t *) (pool->start + p) 


这 样 ，bitmap 变 量 将 指向 bitmap 的 首 地 址 ， 同 时 也 指向 第 1 个 页 

面 。 对 于 小 块 内 存 来 说 ，1 个 uintptr_t 类 型 是 注定 存放 不 下 bitmap 的 。 到 
了 按 位 比较 找到 空闲 块 的 时 候 了 ， 然 而 为 了 加 快运 算 速 度 ， 我 们 并 不 
能 总 按照 二 进 制 位 来 循环 进行 ， 可 以 先 用 uintptr_t 类 型 快速 与 
Oxffffffffffffffff (下 文 的 NGX_SLAB_BUSY 宏 ) 比较 ， 如 果 相 等 则 说 明 
没有 空闲 块 ， 而 不 等 时 才 有 必要 按 二 进 制 位 慢 慢 地 找 出 那个 空闲 块 。 
所 以 ， 现 在 我 们 有 必要 知道 ， 多 少 个 uintptr_t 类 型 可 以 完整 地 表达 该 页 
面 的 bitmap? 用 页 面 大 小 除 以 块 大 小 可 以 知道 页 面 能 存放 多 少 个 块 ， 除 


以 8 就 可 以 知道 需要 多 少 字 刷 来 存放 bitmap ， 再 除 ee 
以 知道 需要 多 少 个 uintptr_t 来 存放 bitmap。 实际 上 ， 这 一 系列 操作 下 面 
这 行 语 句 束 可 以 做 到 : 


ngx_uint_t map = (1 << (ngx_pagesize_ shift - shift)) 
/ (sizeof(uintptr_t) * 8); 


这 里 避免 了 更 慢 的 除法 ， 这 就 是 位 操作 的 优势 ! map 就 是 bitmap 需 
要 的 总 uintptr_t 数 。 下 面 我 们 看 看 怎样 在 一 个 存放 小 块 内 存 的 半 满 面 
中 ， 根 据 bitmap 的 位 操作 快速 找到 空 内 块 。 


/7 共和 需要 


map 个 


uintptr_t 才 能 表达 完整 的 


bitmap 
for (uintptr_t n = 0; n < map; n++) { 
/ 通过 


uintptr_t 与 


NGX_SLAB_BUSY 比 较 ， 快 速 


pass 掉 全 满 的 


uintptr_t 
if Sb != NGX_SLAB_BUSY) { 
/ 确认 当前 


bitmap[n] 上 有 空闲 块 ， 再 一 位 一 位 的 查找 


for (uintptr _t m= 1, i= 0; m; m <<= 1, i++) { 
// 这 个 位 如 果 是 


1 则 表示 内 存 块 已 被 使 用 ， 继 续 循 环 遍历 


if ((bitmap[n] & m)) { 
continue; 


} 
// 既然 找到 了 空闲 位 ， 先 把 这 个 位 从 


bitmap[n] |= m; 


// 


bit 到 底 对 应 着 该 页 


n 和 


i 即 可 得 到 ， 


// nNn*sizeof (uintptr_t)*8+i。 由 


<<shift 即 可 得 到 该 内 存 块 在 页 巴 


那么 ， 当 


前 的 这 个 
面 的 第 几 个 内 存 块 呢 ? 从 


上 的 对 


忆 偏 移 量 


演 


i= ((n * sizeof(uintptr_t) * 8) << shift) 
+ (i << shift); 


// p 就 是 那个 空闲 块 的 


bitmap 加 上 字 节 偏 移 


i 得 到 


p= 


// 后 续 还 有 操作 ， 


地 址 ， 


(uintptr_t) bitmap + i; 


例如 


如 果 没 有 半 满 页 ， 则 需 


交 页 中 的 bitmap 。 


风 * 


// page 是 从 


free 空 内 链表 


// 再 左 移 


FP 新 分 配 出 的 
pages 数 组 相 减 后 即 可 得 到 是 第 几 个 页 面 ， 


判断 如 果 页 面 


半 满 变 为 全 满 ， 则 脱离 链表 


F 


要 从 free 空 


页 面 ， 


ngx_pagesize_shift 即 表示 从 


start 起 到 实际 页 巴 


的 字 节 1 


扁 移 站 


x 町 链表 中 分 配 出 1 页 ， 再 初始 化 


我 们 来 看 看 源码 中 是 怎样 用 位 操作 为 初始 化 bitmap 


p = (page - pool->pages) << ngx_pagesize_ shift,; 
// bitmap 既 是 页 面 的 首 地 址 ， 也 有 是 


bitmap 的 起 始 


bitmap = (uintptr_t *) (pool->start + p); 
// s 为 该 页 存放 的 块 大 小 


s= 1 << shift,; 
// n 表 示 需 要 多 少 个 内 存 块 才能 放 得 下 整个 


bitmap 
n= (1 << (ngx_pagesize _ shift - shift)) A/ 8 / s; 
if (n == 0) { 

n = 1; 


} 
// 因为 前 


n 个 内 存 块 已 经 用 于 
] 不 可 以 再 被 使 用 ， 所 以 置 这 些 内 存 块 对 应 的 


bitmap 了 ， 它 


bit 位 为 


1。 因 为 


于 


// bitmap 这 里 占用 的 内 存 块 数 ， 不 可 能 连 


个 


uintptr_t 都 放 不 下 ， 所 以 只 需要 设置 第 
pla 
uintptr_t 即 可 


bitmap[0] = (2 << n) - 1; 
// map 表示 需 要 多 少 个 


uintptr_t 才 能 放 得 下 整个 


bitmap 
map = (1 << (ngx_pagesize_ shift - shift)) / (sizeof(uintptr_t) 
for (i = 1; i < map; i++) { 


// 设置 剩余 的 


bit 位 为 


0 
bitmap[I] = 0; 


根据 前 述 

Ss 和 

n 的 意义 ， 可 知 

s*n 就 是 在 这 个 页 面 里 ， 第 


* 8); 


1 个 可 以 使 用 的 空闲 块 的 偏 移 字 节 数 。 


// 再 加 上 该 页 面 与 


-| 


start 间 的 偏 移 量 ， 
p 就 是 空 闪 块 与 


start 间 的 偏 移 量 


p= ((page - pool->pages) << ngx_pagesize shift) + s * n; 
// 于 是 得 到 该 空间 块 的 首 地 址 


p += (uintptr_t) pool->start; 


而 释放 内 存 块 时 ， 位 操作 依然 可 以 大 大 加 速 执行 时 间 。 


void ngx_slab_ free_locked(ngx_Sslab_pool t *pool, void *p) 
// 内 存 块 指针 

p 与 

start 之 间 的 偏 移 字 节 数 ， 除 以 页 面 字 节 数 的 结果 取 整 ， 就 是 

p 所 在 的 页 面 在 所 有 


// 页 面 中 的 序号 


ngx_uint t n= ((u_char *) p - pool->start) >> ngx_pagesize shift; 


// 根据 
n 就 取 到 了 
p 所 在 页 面 的 


ngx_slab_page _t 页 面 描述 结构 体 


ngx_slab_page t * page = &pool->pages[n]; 
// 找到 页 面 对 应 的 


slab 
uintptr_t Slab = page->slab; 
// slab 的 低 


NGX_SLAB_PAGE_MASK 位 存放 的 是 页 面 类 型 


ngx_uint_t type = page->prev & NGX_SLAB_PAGE_MASK; 


拿 到 了 type 后 ， 需 要 对 4 种 页 面 区 别 对 待 。 仍 然 以 小 块 内 存 举例 : 


// 对 于 小 块 内 存 ， 
slab 的 低 
NGX_SLAB_SHIFT_MASK 位 存放 了 内 存 块 大 小 ， 


shift 变 量 取出 了 块 大 小 的 位 移 量 


Shift = Slab & NGX_SLAB_SHIFT_MASK ， 
// size 取 得 的 块 大 小 


size = 1 << shift,; 
// 把 内 存 块 的 首 地 址 
p 按 页 大 小 取 余 数 ， 就 是 

p 相 对 于 该 页 面 首 地 址 的 偏 移 字 节 ， 再 除 以 块 大 小 ， 


// 那么 


n 就 是 该 内 存 块 在 页 面 中 的 序号 


n = ((uintptr_t) p & (ngx_pagesize - 1)) >> Shift' 
// 现在 把 


个 序号 应 用 于 


bitmap。 


bitmap 可 能 由 多 个 


uintptr_t 组 成 ， 而 


n 从 属于 某 一 个 


uintptr_t, 


// 先 把 
n 求 得 
uintptr_t 中 的 余数 表明 这 个 内 存 块 对 应 的 


bit 位 ， 在 其 所 属 的 


uintptr_t 里 的 序号 


// 并 把 


1 左 移 这 些 位 ， 这 样 ， 


m 就 是 
p 内 存 块 
bit 位 所 在 


uintptr_t 中 的 位 


m= (uintptr_t) 1 << (n & (sizeof(uintptr t) * 8 - 1)); 
// n 再 除 以 


uintptr_t 能 够 表达 的 


bit 位 ， 此 时 表示 


p 内 存 块 对 应 的 那个 


bit 位 前 还 有 


bitmap 
ZA 的 


uintptr_t 

n /= (sizeof(uintptr_t) * 8); 
// 把 

p 的 相当 于 一 页 的 低位 去 掉 ， 此 时 


bitmap 就 是 该 页 面 的 首 地 址 ， 也 是 所 有 


bitmap 的 起 始 地 址 


bitmap = (uintptr_t *) ((uintptr t) p & ~(ngx_pagesize - 1)); 
// 


bitmap[n] 与 


m 相 与 ， 可 以 再 次 确认 


p 相 对 应 的 内 存 块 是 否 是 在 使 用 中 ， 如 果 没 有 在 使 用 中 ， 


// 就 是 两 次 释放 了 


if (bitmap[n] & m) { 
// 释放 该 内 存 块 ， 其 实 就 是 把 


bit 位 从 


1 置 为 


0 


bitmap[n] &= ~m; 
// 下 面 还 要 检查 当前 页 面 是 否 完全 没有 已 


内 存 块 了 ， 如 果 是 这 样 ， 需 要 回收 该 页 


党 


对 于 中 等 内 存 块 、 大 块 内 存 块 页 面 来 说 ， 由 于 bitmap 是 放 在 slab 成 
员 中 的 ， 所 以 位 操作 会 更 们 单 ， 这 里 就 略 过 。 


16.3.5” slab 内 存 池 间 的 管理 


Nginx 人 允许 多 个 模块 各 自 独 立地 定义 slab 内 存 池 ， 这 意味 着 可 以 并 
和 存 多 个 slab 内 和 存 池 。 同 时 ，Nginx 人 允许 模块 A 定义 的 内 存 池 被 模块 B 使 
用 ， 这 样 内 存 池 间 必须 被 管理 起 来 。 摘 述 整 个 Nginx 的 ngx_cycle_s 结 构 
体 中 有 一 个 链表 ， 保 存 关 所 有 的 slab 内 存 池 ， 如 下 所 示 : 


struct ngx_cycle sf{ 
ngx_list_t shared memory; 


} 


shared_memory 以 链表 的 方式 你 存 着 ngx_shm_zone_t 结 构 体 。 前 面 
在 16.1 节 中 就 介绍 过 这 个 结构 体 ， 它 对 应 着 1 个 slab 共 享 内 存 池 。 
ngx_shm_zone t 具 有 目 己 的 名 字 ， 还 可 以 定义 目 己 仅 能 够 被 某 个 模块 使 
用 (tag 成员) 。ngx_shared_memory_add 方 法 就 是 在 向 shared_memory 
链表 中 添加 描述 一 个 slab 内 存 江 的 ngx_shm_zone_t 结 构 体 ， 在 
ngx_init_ cycle 方法 中 ，Nginx 会 志 历 shared_memory 链 表 ， 依 次 地 初始 化 
每 一 个 slab 内 存 池 。 


16.4 ”小 结 


本 章 首 先 介绍 使 用 slab 内 存 池 的 方法 ， 并 以 一 个 有 代表 性 的 例子 
介绍 使 用 它 的 方法 ， 读 者 朋友 可 以 结合 访问 本 书 网 站 上 可 以 运行 的 示 
例 代 码 来 阅读 。 


接着 ， 我 们 开始 剖析 它 的 实现 ，slab 也 是 Linux 内 核 中 一 种 优秀 的 
内 存 管理 机 制 ， 理 解 其 设计 思想 不 只 有 助 于 开拓 思路 ， 更 可 以 改进 
它 。 例 如 ，slab 内 存 池 其 实 对 于 大 于 4KB 的 内 存 的 使 用 很 不 友好 ， 在 持 
续 的 分 配 释放 中 ， 连 续 着 的 空 有 页 会 越 来 越 少 ， 尤 其 是 有 些 空闲 页 明 
明 是 连续 的 ， 但 是 可 能 也 认为 它们 是 分 离 的 ， 就 像 图 16-4 中 的 例子 那 
样 。 又 比如 ,假定 我 们 申请 的 内 存 基本 都 是 在 4KB 以 上 的 ， 这 就 不 能 
再 使 用 操作 系统 的 页 大 小 作为 内 存 池 的 页 大 小 了 ， 可 以 通过 增加 页 的 
大 小 以 提高 内 存 的 使 用 率 (注意 : 这 可 能 导致 ngx_slab_ page _{t 页 描述 
的 Slab 成 员 中 存放 的 内 存 块 大 小 位 移 超出 NGX_SLAB_SHIFT_MASK， 


需要 综合 考虑 ) 。 


另外 ，slab 的 源码 体现 了 极为 优秀 的 编码 亏 术 ， 大 量 的 位 操作 极 
大 地 提高 了 效率 ， 非 党 值得 C 程 序 员 们 认真 学 习 。 


